Export (0) Print
Expand All

Troubleshooting Adapters

Because of the wide variety of functionality and configuration options provided by native and line-of-business (LOB) BizTalk Server adapters, troubleshooting can be a challenge. This section provides general troubleshooting techniques useful for all adapters along with adapter-specific advice for many of the LOB and native adapters.

BizTalk Server provides detailed debug information that can be captured with the Tracelog.exe utility application available in the Microsoft Platform SDK. Before you can use this utility, you must install the application and enable the tool. After the tool has been enabled, you can invoke it before troubleshooting your messaging scenario.

To install the Trace Log tool (tracelog.exe)
  1. To download the Trace Log tool, visit the following Microsoft Platform SDK download Web site:

    Windows Server 2003 R2 Platform SDK Web Install

  2. Start the Platform SDK Web installation program by clicking the link for the PSDK-x86.exe file at the bottom of the Web page.

  3. When you are prompted, choose the option for a custom installation.

  4. In the Custom Installation dialog box, click to clear all the available features.

  5. Expand the Microsoft Windows Core SDK feature, and then expand the Tools feature.

  6. Choose the Tools (Intel 64-bit) feature, and then click Will be installed on local hard drive.

  7. Click Next, and then click Next again to start the installation.

    Cc825584.note(en-US,BTS.10).gifNote
    After installing the Platform SDK you will be prompted to reboot because certain components of the Platform SDK will not function correctly until the reboot has been completed. You do not need to reboot to use the Trace Log tool.

To enable BizTalk adapter tracing
  1. At a command prompt, change the current directory to the directory where BizTalk Server 2006 is installed. By default, BizTalk Server 2006 is installed in the Program Files\Microsoft BizTalk Server 2006 directory.

  2. Type the following command, and then press ENTER:

    trace -tools "Path of the Trace Log tool"

    By default, the Trace Log tool is located in the C:\Program Files\Microsoft Platform SDK\Bin directory. You must enclose the path of the Trace Log tool in quotation marks.

    For example, type the following command, and then press ENTER:

    trace -tools "C:\Program Files\Microsoft Platform SDK\Bin"

    Cc825584.note(en-US,BTS.10).gifNote
    The -tools switch indicates to the Trace.cmd file the location of the Tracelog.exe file.

To capture trace output
  1. At a command prompt, change the current directory to the directory where BizTalk Server 2006 is installed. By default, BizTalk Server 2006 is installed in the Program Files\Microsoft BizTalk Server 2006 directory.

  2. At a command prompt, type the following command, and then press ENTER:

    trace -start

  3. Reproduce the scenario for which you want to capture trace output.

  4. At a command prompt, type the following command, and then press ENTER:

    trace -stop

  5. After you stop the trace, a binary file named Bts2006.bin is generated in the folder where BizTalk Server 2006 is installed.

  6. Send the Bts2006.bin file to Microsoft Product Support Services for analysis.

Some adapters have additional support for the trace utility in the form of special providers that supply adapter-specific details. To determine if your adapter provides additional support, check the adapter's documentation.

Cc825584.note(en-US,BTS.10).gifNote
This guide provides information about adapter-specific trace providers where appropriate.

BizTalk Server 2006 ships with a wide selection of adapters that are applicable to many different systems and scenarios. Each of the adapters is unique. The adapters can use different protocols, have different suspend/fail rules, and have different configurations that make a one-size-fits-all approach to error handling difficult.

The following list contains some of the different options available for handling adapter errors:

  • Associate error-processing individual operations, not the batch that contains the operation. The failure of a single message should not affect the batch unless the user requests it.
  • Use SetErrorInfo to report a failure to BizTalk Server. You should also associate the error with the related message if possible.
  • Handle a database-offline condition. The BizTalk service recycles itself if a BizTalk Server database goes offline.
  • Write to the event log. This can be done by using IBTTransportProxy.
  • Handle receive-specific batch errors. If a message fails, the adapter should explicitly call the MoveToSuspendQ API and should try to suspend the message.
  • Handle send-specific batch errors. The adapter can retry, try the next transport, or suspend the message.

For a more comprehensive exploration of the options, see How to Handle Adapter Failures.

The Microsoft Base EDI adapter provides comprehensive electronic data interchange (EDI) messaging functionality to complement the XML messaging capabilities of BizTalk Server 2006.

Enabling Trace

The Base EDI adapter can be configured to generate a trace file containing information about the kernel and one or more of the following subprocesses:

  • Translate
  • Memory
  • Database
  • Network
  • BizTalk connector
  • File connector

Base EDI adapter tracing is controlled through the Base EDI Administration console.

To enable Base EDI adapter tracing
  1. To start the Base EDI Administration console, browse to the <Installation Path>\\EDI\Subsystem directory and double-click EDIBTMMc.msc.

  2. Expand the Microsoft BizTalk Server Base EDI Adapter folder.

  3. Click the Parameters folder.

  4. Right-click the server listed, and then click Properties.

  5. On the EDI Subsystem screen, click the Trace tab and specify a trace file.

  6. Click the items you want to trace. In the sample shown in following figure, the adapter is configured to trace kernel, BizTalk connector and file adapter activity.

    EDI Base adapter configuration screen
    Cc825584.note(en-US,BTS.10).gifNote
    Tracing can have an impact on the performance of your solution. Use tracing with caution and disable it when you no longer need it.

  7. Click OK when finished.

    Future EDI activity will be logged.

General Troubleshooting Questions and Answers

This section contains a set of questions and answers designed to help you resolve issues with the Base EDI adapter.

The destination EDI codelist database was not updated when I deployed my project. How do I update it?

The BizTalk Server application and deployment tools like BTSTask do not implement functionality to update the destination EDI codelist database with the information in the deployed EDI schemas. The codelist must be manually updated using the XSD2EDI tool.

To manually update an EDI codelist
  1. Click Start and then click Run.

  2. Type cmd and then click OK.

  3. At the command prompt, use the cd command to change to the directory that contains the Base EDI schema containing the codelist you want to use for the update. For example, cd c:\Projects\MyEDIProject\Schemas.

  4. At the command prompt, run the XSD2EDI command to update the codelist database. The format of the command is:

    XSD2EDI -c <codelist database> <base EDI schema>

    For example, the following command updates the default codelist database with an X12 4010 850 codelist:

    XSD2EDI -c " C:\Program Files\Microsoft BizTalk Server 2006\EDI\Adapter\CodeLists\EDICodeLists.mdb" "C:\Program Files\Microsoft BizTalk Server 2006\EDI\Adapter\EDI Schemas\X12\4010\850Schema.xsd"

    Cc825584.note(en-US,BTS.10).gifNote
    Use quotes if your path includes spaces. If your path has spaces and you do not use quotes, you will receive a "file not found" error.

  5. Restart the Base EDI service. In Control Panel, double-click Administrative Tools, double-click Services, right-click the BizTalk Base EDI service, and then click Stop. Right-click the service again and then click Start.

  6. At the command prompt, enter COMPEIF to generate the EIF file that is used by the BizTalk Base EDI service at run time.

  7. When you are finished, type exit at the command prompt, and then press ENTER.

Common Errors

You receive errors with event ID 5724 or 5719 when using the Base EDI adapter.

Problem

When you use the adapter, you receive an error that is similar to one of the following messages when using party resolution together with an EDI receive location:

  • The Messaging Engine is dropping the message due to authentication failure. The message came from Receive Location URL "EDI://1234567:ZZ:1234567".
  • There was a failure executing the receive pipeline: "Microsoft.BizTalk.DefaultPipelines.XMLReceive" Source: "Microsoft.BizTalk.Pipeline.Components" Receive Location: "EDI://1234567:ZZ:1234567" Reason: There was an authentication failure. "The party corresponding to the inbound message cannot be identified".
Cause

The issue occurs because the BizTalk Server Base EDI adapter does not support party resolution.

Resolution

Create a custom pipeline or orchestration component to scan the InboundTransportLocation context property value and the ExplorerOM object model to enumerate through a list of parties to find a party that has an EDI qualifier value that matches.

You receive a "Cant make a connection to BizTalk for document" error message when you send a message through a send port that uses the EDI transport

Problem

When you send a message through a send port that uses the EDI transport, you receive an error similar to the following in the event log:

Event Type: Error Event Source: EDI Subsystem Event Category: BizTalk Server 2006 Event ID: 23 Date: MM/DD/YYYY Time: 4:55:34 PM User: N/A Computer: BIZTALKSERVERDescription: Error encountered: ERROR (1030), interchangenr 10037 : COM_SendMessage(): Cant make a connection to BizTalk for document #10037. Errorcode is -1030 ()
Cause

This can occur when you have not configured and enabled a receive location that uses the EDI transport.

Resolution

To resolve this issue, configure and then enable a receive location that is bound to the EDI transport. For more information about configuring a receive location using the EDI transport, see How to Configure a Base EDI Receive Location.

You receive a "Could not connect EDI Subsystem (StartDatabase returned -2) to Database" error message, and the BizTalk Base EDI service does not start

Problem

When you try to start the BizTalk Base EDI service, you receive an error message that is similar to "Could not connect EDI Subsystem (StartDatabase returned -2) to Database" in the Application log and the Base EDI service does not start.

Cause

This problem occurs if the following conditions are true:

  • The BizTalk Base EDI database is on a remote computer that is running Microsoft SQL Server 2000 or Microsoft SQL Server 2005.
  • The SQL Server client tools are not installed on the computer that is running the Base EDI service.
Resolution

To resolve this problem, install the SQL Server client tools on the computer that is running the BizTalk Base EDI service. After you install the SQL Server client tools, you can successfully start the BizTalk Base EDI service.

Cc825584.note(en-US,BTS.10).gifNote
SQL Server client tools can be found on the SQL Server installation CD.

You receive an error in the event log similar to "index was outside the bounds of the array" when validating or sending an EDI document

Problem

When you try to validate an EDI document or when you try to send an EDI document in Microsoft BizTalk Server 2006, an Error event that resembles the following may be logged in the event log:

Event Type: ErrorEvent Source: EDI TransmitterEvent Category: BizTalk Server 2006Event ID: 27Description:Transfer of message(s) to EDI Subsystem failed. Index was outside the bounds of the array.
Cause

This issue occurs if one of the following conditions is true:

  • The BizTalk Base EDI service and the BizTalk Server Host service do not use the same logon credentials.
  • The logon account for the BizTalk Base EDI service and for the BizTalk Server Host service does not have the permissions that are required to access the BizTalkEDIDb database and the Configuration database.
  • The user who configured the EDI adapter is not a member of the EDI Subsystem Users group and of the BizTalk Server Administrators group.
Resolution

The user account that is configured as the logon account for the BizTalk Server Host service must be a member of the EDI Subsystem Users group. If the user account that is configured as the logon account for the BizTalk Server Host service is not a member of the EDI Subsystem Users group, the EDI transmitter cannot connect to the EDI subsystem because of insufficient permissions. Therefore, the Error event in the event log states that there is a transmission failure.

To resolve, try one of the following methods:

  • Verify the service logon credentials. Verify that the BizTalk Base EDI service and the BizTalk Server Host service use the same logon credentials.
  • Verify the database permissions. Verify that the user account that is configured as the logon account for the BizTalk Base EDI service and for the BizTalk Server Host service has the permissions that are required to access the BizTalkEDIDb database and the Configuration database.
  • Verify the group membership. Verify that the user who configured the EDI adapter is a member of the EDI Subsystem Users group and of the BizTalk Server Administrators group.

For more details on this issue, see KB article 921993.

The File adapter is in charge of reading and writing messages from files to and from the BizTalk Server MessageBox database.

General Troubleshooting Questions and Answers

This section contains a set of questions and answers designed to help you resolve issues with the File adapter.

Why isn't my file being picked up by the File receive adapter?

Read-only or system files are not picked up by the File receive adapter and will not be published to the BizTalk Server MessageBox database. Usually the problem is due to a read-only file that was originally copied from a read-only source like a CD-ROM. Files copied from these locations remain read-only until you use Windows Explorer or the MS-DOS attrib.exe utility to turn off the read-only attribute.

If you turn off the read-only flag on a file in a receive location, the File receive adapter will process it.

The File receive adapter also does not pick up files for which it has insufficient rights and files that cannot be exclusively locked. To correct these problems, verify the security settings of the receive location and ensure that any files present are not being held by other processes.

One way to peek at what is happening with your files is to use the Microsoft FileMon utility.

To use FileMon to diagnose File adapter errors
  1. Download the FileMon utility from www.sysinternals.com.

  2. Install the FileMon utility on the server that hosts the folder or share that is being read from or written to by the File adapter.

  3. Launch the FileMon utility and apply a filter to monitor only file accesses that are being made by the BizTalk Host instance that the file adapter handlers are running in (for example, BTSNTSvc.exe).

  4. Run the scenario that caused the problem.

  5. Disable file monitoring in the FileMon utility, and then save the generated log file to disk.

  6. Review the generated log file for any errors.

Why won't the File adapter accept my file name and/or file mask?

The BizTalk File adapter file name and file mask properties are validated at design time using the following rules:

  • Only one file mask or file name can be specified per receive location or send port.
  • The file name and file mask cannot include a full or partial path specification.
  • The fields are not case-sensitive.
  • The file name cannot contain any of the following characters: < > : / | " ? * ;
  • The file mask cannot contain any of the following characters: < > : / | " ;
  • You cannot use any of the reserved device names (CON, PRN, CLOCK$, NUL, LPT1, and so on) as the name of a file or as a file extension.
  • Only the first three characters in a file mask extension are considered when matching files. This means "*.xml" will match "a.xml" and "b.xmlxyzabc"; the mask "*.xmlq" will match the same files.
  • The total length of the file path, file mask, and file name must not exceed 256 characters.
  • The file path cannot begin with "\\?".
  • Mapped network drive letters cannot be used because they are user-session based.

For more information about the restrictions of the File adapter, see Restrictions When Configuring the File Adapter.

Why won't the File Adapter process my entire batch of files?

The file adapter may not have enough operating system resources to process all of the messages in a batch concurrently when running on a non-server operating system like Microsoft Windows 2000 or Microsoft Windows XP.

The FTP adapter exchanges data between an FTP server and Microsoft BizTalk Server, and allows for the integration of vital data stored on a variety of platforms with line-of-business applications.

General Troubleshooting Questions and Answers

This section contains a set of questions and answers designed to help you resolve issues with the FTP adapter.

How do I enable logging?

You can enable and configure logging by using the Log folder option in the FTP Transport Properties dialog box when configuring a receive location or send port with the FTP transport type.

Depending upon your FTP server software, you may be able to configure logging for the FTP servers connected to by the BizTalk FTP adapter. Check the documentation for your server to assess your options.

Why does the FTP adapter duplicate or lose data?

If the FTP adapter retrieves a document from the FTP server that is still being written to by the host application, the retrieved document will be incomplete. If the FTP adapter retrieves an incomplete copy of the original document, data duplication or data loss may occur in the following scenarios:

  • If the original document is still being written to the FTP server by the host application, the FTP adapter cannot delete the document and will retrieve another copy of the document at the next polling interval that is configured for the receive location. This behavior causes document duplication to occur.
  • If the host application has finished writing the document to the FTP server, the document will be deleted. This behavior will cause data loss to occur.

To avoid this behavior, use one of the following methods:

  • Configure the host application to write to a temporary folder on the same hard disk as the public FTP folder and to periodically move the contents of the temporary folder to the FTP folder. The temporary folder should be on the same hard disk as the public FTP folder to make sure that the move operation is atomic. An atomic operation is an operation that is functionally indivisible. If you write data to the public FTP folder by using the BizTalk Server 2006 FTP adapter, you can do this by specifying a Temporary Folder property in the FTP Transport Properties dialog box when you configure a send port.
  • Configure the FTP receive location to operate within a service window when the host application is not writing data to the FTP server. You can specify the service window when you configure the receive location properties.

Common Errors

You receive a "Failure occurred in parsing the remote folder listing" error message when you try to retrieve documents from or send documents to an FTP server

Problem

When you try to retrieve documents from or send documents to an FTP server by using the Microsoft BizTalk Server 2006 FTP adapter, you receive an error message that is similar to the following:

A failure occurred in parsing the remote folder listing.

Cause

You may receive this error message if the following conditions are true:

  • The receive handler or the send handler for the BizTalk Server 2006 FTP adapter is configured to use a firewall mode of Passive.
  • The target FTP server does not permit passive connections.
Resolution

To resolve this behavior, use one of the following methods:

  • Configure the receive handler or the send handler, or both, for the BizTalk Server 2006 FTP adapter to use a firewall mode of Active.
  • Configure the target FTP server to permit passive connections.

The FTP adapter can be used to connect to FTP servers on systems ranging from Solaris and Linux to AS/400. For more information about connecting to legacy systems, see Configuring an FTP Adapter to Work with Legacy Hosts.

FTP receive adapter fails to publish message if receive pipeline processing time exceeds server time-out

Problem

A message received via the FTP adapter is not published to the MessageBox database. You may see errors similar to the following in the Application log for the BizTalk Server computer:

Event Type:Error
Event Source:BizTalk Server 2006
Event Category:BizTalk Server 2006 
Event ID:5719
Date:6/30/2006
Time:12:08:55 PM
User:N/A
Computer:BIZTALKSERVER
Description:
There was a failure executing the receive pipeline: "Microsoft.BizTalk.DefaultPipelines.PassThruReceive, Microsoft.BizTalk.DefaultPipelines, Version=3.0.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" Source: "Pipeline " Receive Port: "ReceivePort1" URI: "ftp://FTPSERVER:21/*.txt" Reason: Unable to receive the file "file.txt   " from the FTP server.

and

Event Type:Warning
Event Source:BizTalk Server 2006
Event Category:BizTalk Server 2006 
Event ID:5740
Date:6/30/2006
Time:12:08:56 PM
User:N/A
Computer:BIZTALKSERVER
Description:
The adapter "FTP" raised an error message. Details "Unable to receive the file "file.txt   " from the FTP server. ".
Cause

The time taken to complete pipeline processing exceeds the FTP connection time-out.

Resolution

Use one of the following methods to mitigate this problem:

  • Increase the connection time-out value. Set the idle time-out value on the FTP server to be at least the amount of the time it takes to process the file.
  • Use the Temporary Folder feature on the receive location. In this case, the FTP adapter copies the file to the temporary folder (typically the local disk). It typically takes less time to copy the file to the local disk than to run the message through the pipeline and persist it to the MessageBox database, which effectively reduces the idle time.

The HTTP adapter is used to exchange information between Microsoft BizTalk Server and an application by means of the HTTP protocol. The HTTP adapter consists of two adapters—a receive adapter and a send adapter. The HTTP receive adapter is a Microsoft Internet Information Services (IIS) Internet Server Application Programming Interface (ISAPI) extension that the IIS process hosts, and it controls the receive locations that use the HTTP adapter. The HTTP send adapter controls the send ports that use the HTTP adapter.

General Troubleshooting Questions and Answers

This section contains a set of questions and answers designed to help you resolve issues with the HTTP adapter.

Where are the IIS and HTTPERR log files?

You can often diagnose HTTP adapter issues by using the IIS and HTTPERR log files supplied by the IIS server. By default, the IIS log files can be found in %WinDir%\system32\LogFiles\W3SVC1\ and the HTTPERR log files can be found in %WinDir%\system32\LogFiles\HTTPERR.

Cc825584.note(en-US,BTS.10).gifNote
The HTTPERR log file can only be found on a Windows Server 2003-based computer.

I am using the x64 edition of Microsoft Windows Server 2003. How do I use the 64-bit version of the HTTP adapter?

The 64-bit version of the HTTP receive adapter is installed to the <drive>\Program Files (x86)\Microsoft BizTalk Server 2006\HttpReceive64 directory of your BizTalk server by default. To run the 64-bit version of the HTTP receive adapter in 64-bit native mode you must execute the following script from a command prompt:

cscript %SystemDrive%\inetpub\AdminScripts\adsutil.vbs set w3svc/AppPools/Enable32bitAppOnWin64 0 
C:\WINDOWS\Microsoft.NET\Framework64\v2.0.50215>aspnet_regiis.exe -i

Common Errors

You receive error 405 (Method Not Allowed) on your HTTP receive location

Problem

You are receiving error 405 (Method Not Allowed) when receiving messages through an HTTP receive location.

Cause

The virtual folder containing BTSHTTPReceive.dll does not have permissions to run scripts and executables.

Resolution

Verify that your virtual folder containing BTSHTTPReceive.dll has the Execute Permissions property value of Scripts and Executables. To verify this, right-click the virtual directory, click Properties, and then click the Virtual Directory tab.

You receive error 500 (Internal Server Error) on your HTTP receive location

Problem

You are receiving error 500 (Internal Server Error) when receiving messages through an HTTP receive location.

Cause

There are two potential causes:

  • The identity for the IIS out-of-process host has insufficient privileges to access BizTalk Server.
  • The receive port that corresponds to the receive location has not been started in BizTalk Server.
Resolution

To resolve, try the following:

  • Verify that the identity for the out-of-process host is set to a user that belongs to the BizTalk Isolated Host Users group. This user account must have access to the BizTalk Management database, so do not use the IWAM_<server name> user account (which is the default).
  • Verify that the port corresponding to the receive location has been started.

Microsoft BizTalk Adapter for JD Edwards EnterpriseOne enables you to use JD Edwards EnterpriseOne business functions within BizTalk Server.

Accessing JD Edwards Event Trace for Windows Providers

You can view detailed logs of receiver, transmitter, and management activity within the JD Edwards adapter by using the JD Edwards EnterpriseOne Event Trace for Windows providers.

BizTalk Adapter for JD Edwards EnterpriseOne contains three providers, allowing you to log different kinds of messages:

  • Receiver Logging Provider. The <Trace element> switch is -receiver. Use -receiver to get any messages from the log that were received by the adapter at run time.
  • Transmitter Logging Provider. The <Trace element> switch is -transmitter. Use -transmitter to get any messages from the log that were transmitted by the adapter at run time.
  • Management Logging Provider. The <Trace element> switch is -management. Use -management to get any messages from the log that were generated during browsing of the server system.

To use Event Trace for Windows, run the BizTalk Adapter for JD Edwards EnterpriseOne command, BTAJDEEnterpriseOneTrace.cmd. You use this command as follows:

BTAJDEEnterpriseOneTrace <Trace element> -start [-cir <MB>| 
-seq <MB>] [-rt] logfile
BTAJDEEnterpriseOneTrace <Trace element> -stop

For more information about using JD Edwards EnterpriseOne providers with Event Trace for Windows, see Using Event Tracing for Windows.

Enabling Java Trace

The JD Edwards EnterpriseOne adapter can be configured to write tracing information to a file. To enable tracing, open the jdeinterop.ini file located in the <Adapter Installation Path>\J.D. Edwards EnterpriseOne(r)\Config directory and find the following entry:

[JDBj-LOGS]
jdbcTrace=false

To enable trace, change the value of jdbcTrace to true as shown:

[JDBj-LOGS]
jdbcTrace=true

After importing metadata, you can find the log file in the root directory with a name similar to YYYYMMDD.log; for example, if the log were created on February 2, 2006 the log file would have a name similar to "20060202.log".

Common Errors

JAR inconsistencies

Problem

General connection problems when trying to connect to the JD Edwards EnterpriseOne system.

Cause

Incompatible JAR files.

Solution

Generate JAR files in the environment from which you plan to access the JD Edwards EnterpriseOne system. Copying JAR files from one environment to another results in unpredictable behavior.

I-JDE0043 or I-JDE0027

Problem

Logon failed.

Cause

There are many potential causes:

  • The JD Edwards EnterpriseOne JAR files are missing.
  • You have specified the wrong application server name, port number, environment, or path for the configuration file.
  • Your logon credentials are incorrect.
  • The ideinterop.ini file is bad or missing.
Resolution

To resolve this problem, try the following:

  • Verify your credentials and CLASSPATH setting. The CLASSPATH setting can be found on the Advanced tab of the System Properties dialog box. Click Environment Variables to review the current environment variables for your computer.
  • Fix your logon credentials.
  • Repair or replace the ideinterop.ini configuration file.

I-JDE0048

Problem

The BizTalk Adapter for JD Edwards EnterpriseOne log contains entries about missing or empty jdearglist.txt file.

Cause

Jdearglist.txt is missing or empty.

Resolution

You must create jdearglist.txt using a text editor, with entries describing these parameters, and save it in the folder C:\Program Files\Microsoft BizTalk Adapters\JDEEnterpriseOne\config. If this file does not exist or is empty, an informational message appears in the BizTalk Adapter for JD Edwards EnterpriseOne log when the adapter opens.

For more information about the format of jdearglist.txt, see Handling String Values.

Microsoft BizTalk Adapter for Oracle E-Business Suite is a development and run-time environment for line-of-business process management and automation that enables you to reuse your existing Oracle E-Business Suite procedures and applications with other applications. It is based on the Oracle ODBC driver.

Common Errors

I-OAP0007

Problem

You receive error I-0AP0007 when calling a method on a connection.

Cause

A call was made on a connection that was not created from the Login method of the session object.

Resolution

Create the connection by calling the Login method of the session object.

Messaging Engine failed to register the adapter for "Adapter" for the receive location "SomeName"

Problem

Messaging Engine failed to register the adapter for the receive location.

Cause

You are using a receive port and have enabled the port before creating a port in your orchestration to handle the events.

Resolution

Verify that the receive location is valid, and that the isolated adapter runs under an account that has access to the BizTalk Server databases.

You are receiving error "HY104 : [Oracle][ODBC]Invalid precision or scale value" with the INSERT method

Problem

You receive the error "HY104 : [Oracle][ODBC]Invalid precision or scale value" when you use the INSERT method.

Cause

Oracle treats literal numbers differently.

Resolution

Format the numbers with a semicolon instead of with a period. Consult your Oracle documentation for more information about the format of literal values.

IM-004

Problem

While you are using the Add Generate Item Wizard you receive an error similar to the following:

IM004 : [Microsoft][ODBC Driver Manager] Driver's SQLAllocHandle on SQL_HANDLE_ENV failed.

Cause

The ODBC driver manager cannot create an instance of the required database driver.

Resolution

Add the PATH to the ODBC driver client DLLs.

With Microsoft BizTalk Adapter for Oracle Database, you can access stored procedures, tables, and views for Oracle databases that run on Oracle 8i or 9i Database.

Limitations of the Oracle Database Adapter

This section describes some capabilities that the Oracle Database adapter does not support.

Cannot use wildcard characters in send port properties

BizTalk Adapter for Oracle Database does not support using wildcard characters in the following send port property fields:

  • Username
  • Path
  • Service Name

XMLDATATYPE and BFILE are unsupported data types

The adapter does not support XMLDATATYPE and the BFILE data types.

Only RefCursor can be returned from native SQL stored procedure

Use of other types of cursors is unsupported.

Microsoft BizTalk Adapter for PeopleSoft Enterprise enables you to use PeopleSoft objects.

Accessing PeopleSoft Adapter Event Trace for Windows Providers

You can view detailed logs of certain activity within the PeopleSoft Enterprise adapter by using the PeopleSoft Adapter Event Trace for Windows providers with the indicated switches:

  • Receiver Logging Provider. The <Trace element> switch is -receiver.
  • Receiver CastDetails Provider. The <Trace element> switch is -castDetailsReceive.
  • Transmitter Logging Provider. The <Trace element> switch is -transmitter.
  • Transmitter CastDetails Provider. The <Trace element> switch is -castDetailsTransmit.
  • Management Logging Provider. The <Trace element> switch is -management.

To use Event Trace for Windows, run the BizTalk Adapter for PeopleSoft command, BTAPeopleSoftTrace.cmd. You use this command as follows:

BTAPeopleSoftTrace <Trace element> -start [-cir <MB>| 
-seq <MB>] [-rt] logfile
BTAPeopleSoftTrace <Trace element> -stop

For more information about using PeopleSoft providers with Event Trace for Windows, see Using Event Tracing for Windows.

Common Errors

E-JNI0004

Problem

A Java exception is thrown when trying to use the adapter.

Cause

Bad or missing psjoa.jar file.

Resolution

Verify the existence and location of the psjoa.jar file.

E-PSFT0030

Problem

Failed to instantiate Component Interface Beans.

Cause

Bad or missing psjoa.jar file.

Resolution

Verify the existence and location of the psjoa.jar file.

E-PSFT0019

Problem

Connection to PeopleSoft Application Server failed.

Cause

Unknown PeopleSoft host name was used.

Resolution

Verify the PeopleSoft host and user parameters.

E-PSFT0024

Problem

Connection failed with an error message similar to "JavaClient is an Invalid User name, or you typed the wrong password".

Cause

The wrong user name and password were used.

Resolution

Verify the user name and password you are using and ensure they are properly cased. PeopleSoft user names and passwords are case sensitive.

The MQSeries adapter serves as a bridge between Microsoft BizTalk Server and IBM MQSeries servers, enabling you to use a full range of options in creating your business processes.

General Troubleshooting Questions and Answers

This section contains a set of questions and answers designed to help you resolve issues with the MQSeries adapter.

How do I programmatically modify jobs and mappings?

In some circumstances, you must create or modify jobs and mappings in the Microsoft BizTalk Adapter for MQSeries without using the Microsoft Management Console (MMC) interface for the adapter. To do so, you modify the corresponding information in the registry. But first a warning:

Cc825584.Caution(en-US,BTS.10).gifWarning
If you modify the registry incorrectly, you may cause serious problems that may require you to reinstall your operating system. Microsoft cannot guarantee that you can solve problems that result from modifying the registry. Modify the registry at your own risk.

Do not modify the registry unless you have a pressing need, and then do so only after making a backup.

You can find configuration information for jobs and mappings for the MQSeries adapter in registry keys by job. Each job creates a registry key using the following format:

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\MTBSvc\Parameters\JobList\JobName]

Under each job key is a child key for each mapping in the job using the following format:

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\MTBSvc\Parameters\JobList\JobName\MappingName]

Both the job and mapping keys can contain a variety of child keys. For more details on the keys available, see KB Article 816468.

Common Errors

Adapter raises error "Access Denied" when sending and receiving messages

Problem

In Microsoft BizTalk Server 2004 and Microsoft BizTalk Server 2006, you may receive an error message that resembles one of the following when you use the BizTalk Adapter for MQSeries to send messages to and to receive messages from an MQSeries server:

The adapter "MQSeries" raised an error message. Details "The adapter has encountered an 'Access Denied' error while attempting to contact the COM+ object on the MQSeries server. Ensure the BizTalk account is added to the Role on the MQSAgent COM+ application."

The adapter failed to transmit message going to send port "MQS://servername/queuename". It will be retransmitted after the retry interval specified for this Send Port. Details: "The adapter has encountered an 'Access Denied' error while attempting to contact the COM+ object on the MQSeries server. Ensure the BizTalk account is added to the Role on the MQSAgent COM+ application."

Additionally, when you try to create the receive location or the send port that is configured to use the BizTalk Adapter for MQSeries, you may receive the following warning message in Event Viewer:

The adapter "MQSeries" raised an error message. Details "The adapter has encountered an 'Access Denied' error while attempting to contact the COM+ object on the MQSeries server. Ensure the BizTalk account is added to the Role on the MQSAgent COM+ application."

Cause

This issue may occur if one or more of the following conditions are true:

  • The host account for the BizTalk Adapter for MQSeries does not have the required permissions for the MQSAgent COM+ application (MQSAgent2) or for the MQSAgent2 COM+ application on the MQSeries server.
  • On a Microsoft Windows Server 2003 Service Pack 1-based server, the host account for the BizTalk Adapter for MQSeries is not a member of the Distributed COM Users group on the MQSeries server.
Resolution

To resolve this issue, try the following methods. You may have to try more than one method to resolve the issue.

  • Enable network COM+ access on the Microsoft Windows Server 2003-based computer. For details on enabling COM+ access, see How to enable network COM+ access in Windows Server 2003.
  • Configure the Microsoft Distributed Transaction Coordinator (DTC) settings on the server where BizTalk Server is installed and on the server where the MSQAgent application or the MSQAgent2 application is running.
  • Verify that the host account for the BizTalk Adapter for MQSeries is added to the role that was created in the MQSAgent COM+ application or in the MQSAgent2 COM+ application on the MQSeries server. You can verify this in Component Services.
  • On a Windows Server 2003 Service Pack 1-based server, examine the group memberships of the host account for the BizTalk Adapter for MQSeries. Make sure that the account is a member of the Distributed COM Users group on the MQSeries server where the MQSAgent COM+ application or the MQSAgent2 COM+ application is installed.

You can use MQSender.exe to send messages to and from remote computers and re-create scenarios for troubleshooting this issue.

The MSMQ adapter lets you use Microsoft Message Queuing 2.0 and Message Queuing 3.0 from BizTalk Server 2006.

General Troubleshooting Questions and Answers

This section contains a set of questions and answers designed to help you resolve issues with the MSMQ adapter.

Why doesn't the MSMQ adapter work with my dependent MSMQ client?

The Microsoft BizTalk Adapter for MSMQ is currently not supported when Microsoft Message Queuing (also known as MSMQ) is installed as a dependent client. The BizTalk Adapter for MSMQ checks for an existing installation of Message Queuing. If the existing installation of Message Queuing is configured as a dependent client, the BizTalk Adapter for MSMQ is not supported.

How do I access MSMQ adapter context properties for my project?

If you need to develop a BizTalk project that will make use of the MSMQ adapter context properties, the BizTalk project must contain a reference to the file Microsoft.BizTalk.Adapter.MSMQ.MsmqAdapterProperties.dll located in the BizTalk Server 2006 installation directory. The MSMQ adapter context properties are exposed by this file rather then by Microsoft.BizTalk.GlobalPropertySchemas.dll to maintain backward compatibility with applications that were developed with BizTalk Server 2004.

Where are my failed transaction messages going?

If a transactional message cannot be delivered to a remote queue, it is placed in the local Transactional Dead Letter queue without the adapter raising an error. To remedy this, you can either periodically monitor the Dead Letter queue or implement acknowledgments.

Why aren't my receive locations processing documents?

MSMQ Adapter receive locations will not process documents if there are insufficient threads available in the .NET thread pool associated with the BizTalk Host instance that the MSMQ adapter receive handler is running in. To increase the number of available threads in the .NET thread pool for the host instance, follow the steps in the "CLR Hosting thread values for the host" section of the topic Configuration Parameters that Affect Adapter Performance.

Recommended values for thread settings are summarized in the following table.

DWORD entry Recommended value

MaxIOThreads

Number of MSMQ receive locations bound to the MSMQ adapter receive handler × 2

MaxWorkerThreads

Number of MSMQ receive locations bound to the MSMQ adapter receive handler × 2

MinIOThreads

Number of MSMQ receive locations bound to the MSMQ adapter receive handler.

MinWorkerThreads

Number of MSMQ receive locations bound to the MSMQ adapter receive handler.

The Microsoft® BizTalk® Adapter v2.0 for mySAP™ Business Suite ("the SAP adapter") provides a way to integrate applications that use BizTalk Server as a hub between one or more SAP application servers.

Using SAP RFC and CPIC Trace

You can use RFC and CPIC trace to troubleshoot SAP adapter activity and to pinpoint problems. The RFC trace captures the following information:

  • Which function modules were called remotely by the program to be analyzed
  • Whether the RFC was executed successfully
  • The total time used to process the remote call
  • The type of RFC communication (RFC client or RFC server)
  • The instance the remote call was executed on
  • The technical parameters characterizing the instance
  • The number of bytes sent and received at the RFC

The CPIC trace captures the following information:

  • How the error occurred
  • When the error last occurred
  • Error number and description

You can use the following script to enable and disable RFC or CPIC tracing:

Set oShell = CreateObject("WScript.Shell")
Set oUserEnv = oShell.Environment("SYSTEM")
'RFC_TRACE
'0 = No trace
'1 = Trace
oUserEnv("RFC_TRACE") = 1
' CPIC_TRACE
' 0 = No trace
'1 = Write error messages in trace file
'2 = Full trace
'3 = Include trace data blocks
oUserEnv("CPIC_TRACE") = 1
oUserEnv("RFC_TRACE_DIR") = "c:\RFCTrace"

Common Errors

Connection error occurs when you deploy an orchestration using a binding file

Problem

When you deploy the orchestration project using a binding file, BizTalk Server displays the following connection error in Event Viewer:

The adapter failed to transmit message going to send port "sap://Ebizides620:00/800/<username>/en/". It will be retransmitted after the retry interval specified for this Send Port. Details: "Name or password is incorrect. Please re-enter."

Cause

The password was not assigned correctly to the password field of BizTalk Explorer.

Resolution

Correct the password by manually updating the binding file that is used for deploying on another computer.

BizTalk service is not receiving IDOCs from the SAP system

Problem

The BizTalk service is not receiving IDOCs.

Cause

There are a few possible causes:

  • The SAP system is trying and failing to send the IDOCs.
  • BizTalk Server is not logged on to SAP.
  • The RPC connection is failing, or the mechanism for submitting IDOCs is failing.
Resolution

Try the following to resolve the problem:

  • Examine the list of sent IDOCs. Execute the we05 transaction to bring up a search page that you can use to query for IDOCs submitted within a certain time period.
  • View the sm58 transaction output. Execute the sm58 transaction. If there are IDOC attempts listed here, then the SAP system is attempting and failing to send the IDOCs.
  • Verify the BizTalk Server connection. Verify active connections to SAP by running the smgw transaction and then using the Goto menu to navigate to Logged on clients.
  • Test the RPC connection. Use the sm59 transaction to list current RPC ports, and then test a port by clicking the Test Connection button on an individual port's details screen.

Debugging Stored Procedures

Programming errors in stored procedures can often be more easily identified by stepping through the code one statement at a time. This gives you the opportunity to not only verify stored procedure arguments and variables, but also check data in tables, error values, and other variables that are affected by the stored procedure.

To debug a SQL Server stored procedure using Visual Studio
  1. Open a BizTalk project using Visual Studio 2005.

  2. On the Visual Studio View menu, click Server Explorer.

  3. In the Server Explorer pane, right-click Data Connections and then click Add Connection.

  4. On the Choose Data Source screen, click Microsoft SQL Server and then click Continue.

  5. On the Add Connection screen, choose a server name from the drop-down list or type a server name, and choose a logon method. If you choose Use SQL Server Authentication, supply a User name and Password. Choose a database to connect to, and then click OK.

  6. In the Server Explorer pane, expand the database and then expand Stored Procedures to expose the stored procedures.

  7. Right-click one of the stored procedures and then click Step Into Stored Procedure.

  8. On the Run Stored Procedure screen, enter values for each of your stored procedure arguments.

  9. Step through the stored procedure using F10, breakpoints, and the other tools available in Visual Studio 2005.

Troubleshooting Deadlocks

A deadlock occurs when two or more tasks permanently block each other because each task has a lock on a resource that the other tasks are trying to lock. The SQL Server Database Engine automatically detects deadlock cycles within SQL Server; when a cycle is detected, one of the sessions is chosen as a deadlock victim and is terminated with an error to break the deadlock.

The following types of resources can cause blocking that could result in a deadlock:

  • Locks
  • Worker threads
  • Memory
  • Parallel query execution-related resources
  • Multiple Active Result Sets resources

Although deadlocks cannot be completely avoided, they can be identified and minimized through debugging tools and defensive coding techniques.

Debugging deadlocks in SQL Server 2005

To view deadlock information, the SQL Server 2005 database engine provides monitoring tools in the form of two trace flags and the deadlock graph event in SQL Server Profiler. The trace flags provide details in a report format while the deadlock graph provides a graphical view.

The trace flags provide the following information:

  • Trace flag 1204 reports deadlock information formatted by each node involved in the deadlock.
  • Trace flag 1222 formats deadlock information first by processes and then by resources.

Using the SQL Server Profiler, you can add the deadlock graph event to a trace and capture XML data about the process and objects that are involved in a deadlock. SQL Server Profiler can extract the XML document to a deadlock XML (.xdl) file that you can view later in SQL Server Management Studio.

For more information about deadlocks in SQL Server 2005, see Deadlocking.

Debugging deadlocks in SQL Server 2000

To view deadlock information, the SQL Server database engine provides monitoring tools in the form of trace flag 1204 and SQL Profiler. Trace flag 1204 graphs the cycle of dependency among waiting threads, the resources on which the threads are waiting, and which threads hold these resources. SQL Profiler provides information for basic deadlock detection.

For more information about deadlocks in SQL Server 2000, see Deadlocking.

Minimizing deadlocks

Minimizing deadlocks can increase transaction throughput and reduce system overhead because fewer transactions are rolled back or resubmitted. To minimize deadlocks in your application:

  • Access objects in the same order. If all concurrent transactions access objects in the same order, deadlocks are less likely to occur.
  • Avoid user interaction in transactions. This is because the speed of batches running without user intervention is much faster than the speed at which a user can manually respond to queries, such as replying to a prompt for a parameter requested by an application.
  • Keep transactions short and in one batch. Keeping transactions in one batch minimizes network roundtrips during a transaction, reducing possible delays in completing the transaction and releasing locks.
  • Use a lower isolation level. Using a lower isolation level (such as read committed) holds shared locks for a shorter duration than a higher isolation level (such as serializable), and thus may reduce locking contention.
  • Use a row versioning-based isolation level. This can minimize deadlocks that can occur between read and write operations.
  • Use bound connections. Using bound connections, two or more connections opened by the same application can cooperate with each other. Any locks acquired by the secondary connections are held as if they were acquired by the primary connection, and vice versa.

Careful testing of your solution under high-load conditions can reveal deadlock issues early in development. Make sure testing is a part of your solution!

General Troubleshooting Questions and Answers

This section contains a set of questions and answers designed to help you resolve issues with the SQL adapter.

How do I support the Euro symbol (€) when using the SQL adapter?

Due to a limitation in SQLXML 3.0 SP3, the SQL adapter does not support some currency types when using updategrams. Updategrams will work for most currency types, but some currency types, such as the euro, will not work. The workaround is to use a stored procedure and pass money values as strings.

To use a stored procedure in an updategram
  1. Create a stored procedure to wrap the insert.

    Create proc InsertTestTB @pID int, @pPrice varchar(50), @pSymbol char(10)
    As 
    insert into TestTable(ItemID, ItemPrice) values(@pID, @pSymbol + @pPrice)
    
  2. Create an updategram that calls the stored procedure with the appropriate arguments.

    <ns0:InRoot xmlns:ns0="http://Test ">
         <ns0:InsertTestTB pID="1001" pPrice="7.40" pSymbol="€"/>
    </ns0:InRoot>
    

    The currency symbol is passed as an argument into the stored procedure, which then inserts the value correctly.

How do I use a table that has one or more spaces in its name with the SQL adapter?

BizTalk Server does not support using spaces in SQL table names used by the SQL adapter. If you have existing tables whose names contain spaces, you should use an alias for the table name.

For example, the following query is not supported by the SQL adapter:

SELECT  *
FROM    [My Table]

If you modify the query to use an alias, it will work with the SQL adapter:

SELECT  My_Table.*
FROM    [My Table] as My_Table

If you are querying other databases, the syntax may vary.

Common Errors

The SQL Transport Schema Generation Wizard closes unexpectedly in BizTalk Server 2006

Problem

In Microsoft BizTalk Server 2006, the SQL Transport Schema Generation Wizard closes unexpectedly when you try to generate a schema for an SQL adapter send port. You may also receive an error message that resembles the following:

Failed to execute SQL Statement. Please ensure that the supplied syntax is correct. New transaction cannot enlist in the specified transaction coordinator.

Cause

This problem occurs if you try to generate a schema for one of the following updategrams to update a database table in Microsoft SQL Server 2005:

  • Insert
  • Update
  • Delete

The problem occurs when the database table contains a column that has one of the following datatypes:

  • varbinary(MAX)
  • varchar(MAX)
  • nvarchar(MAX)
  • xml

These data types are not supported by the SQL adapter in BizTalk Server.

Resolution

These data types are new data types in SQL Server 2005. When the database table contains a column that has one of these data types, do not use the SQL adapter in BizTalk Server to insert data into the database table or to retrieve data from the database table. Consider writing a custom component to insert and retrieve data.

A syntax error is raised when sending updategrams to the adapter

Problem

When you send an updategram to the SQL send adapter, you an error message similar to the following:

Syntax error converting datetime from character string

Cause

This problem can occur if the SQL table contains a datetime column and the updategram is trying to update that column with an incorrect value.

Resolution

To resolve this issue, do not use the BizTalk Mapper functoids to create the datetime values to map to the updategram. The functoids create a datetime value in the format "1999-05-31T13:20:00.000-05:00". SQL datetime columns require datetime values to be of the format "1999-05-31T13:20:00.000". Instead of using the default date and time functoid, create the datetime value manually by calling the Parse or ParseExact method of the DateTime class.

You get error "Invalid 'name' attribute value" when compiling your solution

Problem

You receive a compilation error similar to the following when compiling your BizTalk Server solution:

"Invalid 'name' attribute value: The '' character, hexadecimal value <hexadecimal value>, cannot begin with a name. An error occurred at file:/<file location>.xsd.

Cause

This problem can occur if the SELECT statement or stored procedure encountered illegal characters, as described in the System.Xml.XmlConvert class, for import in the Add Adapter Wizard.

Resolution

To resolve this error, modify the table or column names listed in the SELECT statement or stored procedure defined in the Add Adapter Wizard so that they contain legal values as defined by the System.Xml.XmlConvert class. For more information about characters supported by the XmlConvert class, see XmlConvert Class.

Columns are missing from generated XML schemas

Problem

Columns are missing from XML schemas generated by the Add Adapter Wizard.

Cause

This problem can occur if the Add Adapter Wizard could not match the XSD data type.

Resolution

To resolve this problem, change columns of type SQL_Variant to a supported data type.

Show:
© 2014 Microsoft