Resolving problems that occur during deployment of message flows

Use the advice given here to help you to resolve problems that can arise during deployment of message flows or message sets.

Procedure

You receive a warning message about the mode of your integration node
The message flow deploys on the test system, but not elsewhere
Error messages about your integration node mode are issued when you create an integration server
Error messages about your integration node mode are issued when you deploy
Error messages about your function level are issued when you deploy
Error messages are issued when you deploy to z/OS
Expected serialization of input is not occurring for a shared queue that serves multiple instances of a message flow on z/OS
You create a configurable service, then deploy a message flow and inbound adapter, but the deployment fails
You have created a WebSphere Adapters message flow that uses secondary adapters, and a naming clash has occurred in the secondary adapters or message sets
You get an authority check failure when you deploy to z/OS
Deployment fails when you have circular project dependencies
Error messages are issued when you deploy

You receive a warning message about the mode of your integration node

About this task

Message BIP1806

Scenario: Warning message BIP1806 is displayed.
Explanation: Your integration node timed out before the command completed. You can set the timeout value on the -w parameter of the mqsimode command, or accept the default value of 60 seconds; see mqsimode command.
Solution: Check that the integration node is started: if it is not started, start it by using the mqsistart command. If it is started, increase the timeout value and run the command again.

Message BIP1808

Scenario: Warning message BIP1808 is displayed.
Explanation: Your integration node is running in a previous version of the product. You must migrate integration node that you created in a version earlier than V6.1.0.2 before you can change the operation mode.
Solution: Upgrade your integration node to at least V6.1.0.2, and run the command again.

Message BIP1821

Scenario: Warning message BIP1821 is displayed.
Explanation: Your integration node is running in a mode that restricts the number of integration servers that you can use; see Restrictions that apply in each operation mode.
Solution: Contact your IBM® representative to upgrade your license, or remove the required number of integration servers; see Deleting an integration server.

Message BIP1822

Scenario: Warning message BIP1822 is displayed.
Explanation: Your integration node is running in a mode that restricts the number of message flows that you can use; see Restrictions that apply in each operation mode.
Solution: Contact your IBM representative to upgrade your license, or delete the required number of message flows; see Deleting a message flow or subflow.

Message BIP1823

Scenario: Warning message BIP1823 is displayed.
Explanation: Your integration node is running in a mode that restricts the types of node that you can use in a message flow; see Restrictions that apply in each operation mode.
Solution: Contact your IBM representative to upgrade your license, rework your message flow to use nodes that are valid in the current mode, or remove the message flows that contain unsupported nodes; see Deleting a message flow or subflow.

Message BIP1824

Scenario: Warning message BIP1824 is displayed.
Explanation: Your integration node is running in the Trial Edition mode and your trial period of 90 days has expired; see Restrictions that apply in each operation mode.
Solution: Contact your IBM representative to upgrade your license.

The message flow deploys on the test system, but not elsewhere

Procedure

Scenario: The message flow that you have developed deploys on the test system, but not elsewhere.
Solution: Carry out the following checks:
- Ensure that you have verified the installation on the target system by creating and starting an integration node, and deploying a single integration server. These actions confirm that the integration node is correctly defined.
- Ensure that the BAR file's broker.xml file contains references to the correct resources for the new system.
- Ensure that any referenced message sets are deployed.
- If database resources or user-defined nodes are not accessible or authorized from the target system, the deploy fails. On distributed systems, ensure that you have defined either ODBC or JDBC connections to your databases so that they can be accessed from the integration node. Also, set the integration node environment to allow access to the databases. On Linux® or UNIX systems, you might have to run a database profile.
- Any user-defined extensions that you are using in your message flow might not load if they cannot be found, or are not linked correctly. Consult the documentation for your operating system for details of tools that can help you to check the binary files of your user-defined extension.

Error messages about your integration node mode are issued when you create an integration server

About this task

Message BIP1825

Scenario: Error message BIP1825 is displayed.
Explanation: The integration server cannot be created because the maximum number of integration servers for the mode of the target integration node has been reached, and creating the integration server causes this limit to be exceeded; see Restrictions that apply in each operation mode. The integration server was not created.
Solution: Reuse an existing integration server, or delete an existing integration server and try the command again; see Deleting an integration server. Alternatively, contact your IBM representative to upgrade your license.

Error messages about your integration node mode are issued when you deploy

About this task

Message BIP1826

Scenario: Error message BIP1826 is displayed.
Explanation: The BAR file cannot be deployed because it causes the integration node to run more message flows than are valid for the current mode of operation of the target integration node; see Restrictions that apply in each operation mode. The BAR file was not deployed.
Solution: Delete message flows from the integration node and try the command again; see Deleting a message flow or subflow. Alternatively, contact your IBM representative to upgrade your license.

Message BIP1827

Scenario: Error message BIP1827 is displayed.
Explanation: The BAR file cannot be deployed because it contains nodes that are not valid for the current mode of the target broker; see Restrictions that apply in each operation mode. The BAR file was not deployed.
Solution: Rework your message flow to use nodes that are valid in the current mode, or remove the message flows that contain unsupported nodes; see Deleting a message flow or subflow. Alternatively, contact your IBM representative to upgrade your license.

Message BIP1828

Scenario: Error message BIP1828 is displayed.
Explanation: The target integration node is running in a trial mode that has expired; see Restrictions that apply in each operation mode. The BAR file was not deployed.
Solution: Contact your IBM representative to upgrade your license. If you have already purchased a valid license for the target integration node, change the integration node to the correct mode by using the mqsimode command; see mqsimode command.

Message BIP1829

Scenario: Error message BIP1829 is displayed.
Explanation: The BAR file cannot be deployed because the maximum number of integration servers for the mode of the target integration node has been reached; see Restrictions that apply in each operation mode. The BAR file was not deployed.
Solution: Delete an existing integration server and try the command again; see Deleting an integration server. Alternatively, contact your IBM representative to upgrade your license.

Error messages about your function level are issued when you deploy

About this task

Message BIP2276

Scenario: Error message BIP2276 is displayed.
Explanation: The integration node received an instruction to create a message flow node of type Node_type in message flow Message_flow. The integration node cannot create nodes of this type because the new functions have not been enabled for this integration node. Use the following command to enable this function, and all other functions:
```
mqsichangebroker IBNODE -f all
```
Solution: Either change the flow to avoid using the unavailable node, or enable the new functions by using the mqsichangebroker command; see mqsichangebroker command.

Error messages are issued when you deploy to z/OS

Procedure

Scenario: The following messages are written to the log when you deploy to z/OS®:

+(MQ05BRK) 0 BIP2070E: A problem was detected with WebSphere MQ while issuing
MQPUT for WebSphere MQ queue SYSTEM.BROKER.ADMIN.REPLY, WebSphere MQ queue 
manager QM_01.  MQCC=2, MQRC=2030.                                    
+(MQ05BRK) 0 BIP2068E: The integration node was unable to put an internal configuration 
message to message queue SYSTEM.BROKER.ADMIN.REPLY.

Explanation: The transmission queue is not large enough for the messages that are issued by IBM Integration Bus.
Solution: See the WebSphere® MQ documentation for details on how to increase the size of the transmission queue.

Expected serialization of input is not occurring for a shared queue that serves multiple instances of a message flow on z/OS

Procedure

Scenario: Expected serialization of input is not occurring for a shared queue that serves multiple instances of a message flow on z/OS.
Explanation: On z/OS, WebSphere MQ supports serialized access to shared resources, such as shared queues, through the use of a connection tag (serialization token) when an application connects to the queue manager that participates in a queue sharing group.
This problem can occur for a number of reasons:
- You have assigned different serialization tokens to the input nodes of the flows that get messages from the shared queue.
- The message flows are running in the same integration server. Serialization can only be effected between flows that are running in different integration servers, either on the same integration node, or on different integration nodes whose queue managers participate in the same queue sharing group.
- The queue managers on which the integration nodes are running are not participating in a queue sharing group, or not participating in the same queue sharing group.
Solution: Carry out the following checks:
- Check that the same z/OS serialization token has been configured for the MQInput nodes in each flow that use the shared queue.
- Check that the message flows are running in different integration servers.
- Check that the integration node queue managers are part of the same queue sharing group, and that no errors are reported from the queue managers in the z/OS system log (SDSF log).

You create a configurable service, then deploy a message flow and inbound adapter, but the deployment fails

Procedure

Scenario: You create a configurable service, then deploy a message flow and inbound adapter, but the deployment fails.
Explanation: When you create a configurable service for an adapter that has not yet been deployed, the connection properties are not fully validated until you deploy the adapter and the message flow that uses that adapter. Therefore, the properties that you set on the configurable service might be invalid.
Solution: Inspect the error message that is returned from the deployment and determine whether the deployment failed because of invalid connection properties on the configurable service. If so, use the mqsichangeproperties command to correct the properties, or use the mqsideleteconfigurableservice command to use the properties that are set on the adapter. Restart the integration node and redeploy the message flow.

You have created a WebSphere Adapters message flow that uses secondary adapters, and a naming clash has occurred in the secondary adapters or message sets

Procedure

Scenario: You have created a WebSphere Adapters message flow that uses secondary adapters, and a naming clash has occurred. You need to know which adapters and message sets the WebSphere Adapters node is using, and if the method names in the adapters or the message type names in the message sets are clashing.
Explanation: Method names must be unique across all primary and secondary adapters, and the message set that is created must not contain any types that share the same name and namespace of existing message sets. Information about secondary adapters and message sets is written to user trace at the following stages.
- When the node is first deployed, information about the current set of secondary adapters and message sets is reported.
- When adapters and message sets are deployed subsequently, information about them is reported at the time of deployment.
- When the message flow, integration node, or integration server is stopped then restarted, information about the entire set of secondary adapters and message sets is written to user trace, including those secondary adapters and message sets that are deployed after the message flow was first deployed.
This information is reported by the following messages.
- BIP3432 and BIP3434 list the adapters and message sets that are available when the node is deployed or when the integration node, integration server, or message flow are restarted.
- BIP3433 reports that a secondary adapter is being deployed and added to the set.
- BIP3435 reports that a secondary message set is being deployed.
- BIP3436 identifies the message set in which each type is being defined.
- BIP3437 identifies message sets that attempt to redefine a type that is already defined.
- BIP3438 identifies the adapter in which each method is being defined.
- BIP3439 identifies adapters that attempt to redefine a method that is already defined.
Messages BIP3436, BIP3437, BIP3438, and BIP3439 are issued when a message is processed to report whether definitions are used for that message.
Solution: The following steps describe how to use user trace when working with secondary adapters.
- When you deploy the flow for the first time
  1. Start user trace.
  2. Deploy your message flow, primary adapter, primary message set, and any secondary adapters or message sets that are ready.
  3. Read user trace, looking out for the messages described.
  4. Optional: Reset user trace, stop and restart the message flow, then read user trace again, looking out for the messages described.
- When you add new adapters and message sets
  1. Start user trace.
  2. Deploy the secondary adapters and message sets.
  3. Read user trace, looking out for the messages described.
  4. Optional: Reset user trace, stop and restart the message flow, then read user trace again, looking out for the messages described.
When you have identified where the naming clash has occurred, you can ensure that names are unique by editing them in the following ways:
- Edit method names by clicking Edit Operations on the Service Generation and Deployment Configuration panel of the Adapter Connection wizard.
- Edit the namespaces of the types in the message set by using the Business Object Namespace control on the Adapter Connection wizard.

You get an authority check failure when you deploy to z/OS

Procedure

Scenario: You deploy a BAR file to z/OS, and you get an authority check failure like the following message:

ICH408I USER(MI09STC ) GROUP(TSOUSER ) NAME(WMB TASK ID         ) 672  
  MI09.SYSTEM.BROKER.AUTH.default CL(MQQUEUE )                         
  PROFILE NOT FOUND - REQUIRED FOR AUTHORITY CHECKING                  
  ACCESS INTENT(READ   )  ACCESS ALLOWED(NONE   )

Explanation: The z/OS queue manager accesses the MQQUEUE security profile class by default.
If you have enabled integration node administration security, and you have specified the names of one or more integration servers in mixed case, the security profiles that you set up are defined in MXQUEUE, because the associated authority queue names are also in mixed case. MQQUEUE does not hold the expected information.
Solution: Change the security profile case parameter for the queue manager.
You can use the ALTER QMGR command to update the SCYCASE parameter to M, or you can modify your start job JCL to set or change this parameter, and restart the queue manager.

Deployment fails when you have circular project dependencies

Procedure

Scenario: Circular project dependencies exist in the projects that you are deploying and deployment fails.
Explanation: A circular project dependency occurs when two or more projects depend on each other.
For example, File A in Project X depends on File B in Project Y, and File C in Project Y depends on File D in Project X. For Project X to build successfully, Project Y must be built first so that Project X can resolve the dependency on File B. However, for Project Y to build successfully, Project X must be built first so that Project Y can resolve the dependency on File D. The IBM Integration Toolkit is based on the Eclipse platform, which does not support circular project dependencies.
Solution: To deploy successfully, avoid circular project dependencies.
For example, if Project X depends on File B in Project Y, and Project Y depends on File D in Project X, move File B to Project Z. The projects must be built in the order Project Z, Project X, then Project Y so that the dependencies can be resolved.

Error messages are issued when you deploy

About this task

Additional error messages that might be generated during a deployment are explained in this section.

Message BIP1106 with WebSphere MQ reason code 2030

Scenario: Error message BIP1106 is issued with reason code 2030 when you are deploying a large message set.
Explanation: The size of the message exceeds the maximum message length of the transmission queue to the integration node queue manager.
Solution: Increase the maximum message length for the transmission queue using the WebSphere MQ alter qlocal command, where the maximum message length (maxmsgl) is in bytes:
```
alter ql(transmit_queue_name) maxmsgl(104857600) 
```
For more information about this command, see the System Administration Guide section of the WebSphere MQ Version 7.5 product documentation online.

Message BIP2066

Scenario: You have initiated a deployment request; for example, you have deployed a BAR file to an integration server. Error message BIP2066 is returned one or more times.
Explanation: The deployment request was not acknowledged by the integration server before the sum of the values for the integration node timeout parameters ConfigurationChangeTimeout and InternalConfigurationTimeout expired.
Solution: Increase these timeout values by specifying the -g and -k parameters of the mqsicreatebroker or mqsichangebroker command. See Setting configuration timeout values for information about factors that affect timeout values, and how to set appropriate values.

Message BIP2080

Scenario: The integration node has started an integration server; for example, if you have issued mqsistart for the integration node, or an error has occurred and the integration server is being recovered. Error message BIP2080 is displayed one or more times.
Explanation: The internal configuration request was not acknowledged by the integration server before the value of the InternalConfigurationTimeout (default 60 seconds) expired.
Solution: Change the configuration timeout by specifying the -k parameter of the mqsicreatebroker or mqsichangebroker command. See Setting configuration timeout values for information about factors that affect timeout values, and how to set appropriate values.

Message BIP2241

Scenario: Error message BIP2241 is displayed.
Explanation: You are attempting to deploy a message flow containing a node that is not available on the target integration node.
Solution: Ensure that the version of the IBM Integration Toolkit in which the message flow has been developed matches the version of the integration node to which the message flow is being deployed. If the message flow is using a user-defined node, or a node supplied in a SupportPac, ensure that the runtime node implementation has been correctly installed on the computer on which the integration node is running. If your message flow includes a user-defined node, see Installing user-defined extension runtime files on an integration node. If your message flow includes a node provided in a SupportPac, see the installation information, if supplied, for the SupportPac.

Message BIP2242

Scenario: Error message BIP2242 is displayed.
Explanation: The deployment request (configuration change) was not accepted before the timeout value set by the integration node parameter ConfigurationChangeTimeout expired. This configuration timeout value must be long enough for the message flow to complete processing its current message, then accept the deploy request; the default is 300 seconds.
Solution: Set the configuration timeout values by specifying the -g and -k parameters of the mqsicreatebroker or mqsichangebroker command.

Message BIP3226

Scenario: Error message BIP3226 is displayed; for example:
```
(Semipersistent_Compute1.Main, 27.89) : Array index evaluated to '0' but must 
evaluate to a positive, nonzero integer value.
```
The first insert in BIP3226 (in this example, Semipersistent_Compute1.Main) identifies the node and routine in which the statement occurs. The second insert (in this example, 27.89) identifies the approximate line and column of the index value shown in the third insert (in this example, '0').
Explanation: The validity of using a field reference index of zero was corrected in WebSphere Message Broker Version 7.0. If you have statements in your ESQL modules that include an index of zero, error BIP3226E is generated.
For example, your ESQL module might contain the following statement:
```
SET OutputRoot.XMLNSC.Top.A[0].B = 42;
```
Solution:
You must correct all ESQL statements that use an index of zero to use an index of 1. Statements might use a variable as well as a literal value for the index; check for both possible situations. For example, your changed code might read:
```
SET OutputRoot.XMLNSC.Top.A[1].B = 42;
```

Message BIP7053S

Scenario: When you deploy to an integration node, error message BIP7053S is displayed.
Explanation: This error occurs in a multi TCP/IP stack environment, and indicates that the UNIX System Services (USS) TCP/IP environment has not been set up correctly.
IBM Integration Bus uses USS functions to obtain the host name for a particular system. The following error message is displayed if the default host name is not set up correctly in the USS environment:
```
BIP7053S: Integration node $SYS_mqsi 0 unexpected Java exception java.lang.Error: 
-2103399272!java.net.UnknownHostException :
Hostname: Hostname
```
The host name that is reported in the error message is the one that has been returned to the integration node as a result of the gethostname call.
Solution: Ensure that the TCP/IP environment is configured correctly in USS.

Tagged/Delimited String (TDS) Validator error

Scenario: You try to deploy a message set with a TDS wire format that has an error.

Explanation: The following extract from an error log illustrates what you might see for a TDS Validator error. In this case, the cause of the problem is that the element Town does not have a tag defined.

TDS Extractor Trace File
========================

Beginning Extract..

Extracting Identification Info
Extracting Project Info
Extracting Messages
Extracting Elements
Extracting Compound Types
Extracting Type Members
Extracting Type Members
Extracting Type Members
Extracting Type Members
Extracting Type Members
Beginning Indexing..

Creating Member IDs to Tags Index Table.

Beginning Validation..

Validating Project
Validating Types
ERROR: TDSValidator::ValidateTypeMemberSimpleElement:
  Simple elements in a type with Data Element Separation attribute = Tagged 
  Delimited must have the following attribute set:
  Element Level - Tag
(Element ID: Town)
(Type ID: AddressType)
Return Code: -80

Validating Messages

Trace Info
===========
EXCEPTION: TDSValidator::Validate:
  TDS Validation failed.
    1 errors
    0 warnings
Return Code: -1

Solution: Use the information in the error log to correct the problem.