Resolving problems with user-defined extensions

Advice for dealing with some common problems that can arise when you work with user-defined extensions

About this task

Procedure

You cannot deploy one of your user-defined nodes, despite having a plug-in LIL in the correct directory.

Procedure

  • Scenario: You cannot deploy one of your user-defined nodes, despite having a plug-in LIL in the correct directory.
  • Explanation: You have memset() the data area to zero and have not initialized the CNI_VFT structure with the initialization constant {CNI_VFT_DEFAULT}.
  • Solution: Initialize by copying a predefined initialization structure over the function table area, as follows: 
    static CNI_VFT	virtualFunctionTable = {CNI_VFT_DEFAULT};

    In addition, implement logging from your user-defined node so that you can see if the plug-in API is producing error codes; the integration node does not log these to its own log, unless you take a service trace.

You cannot deploy a flow with one of your user-defined nodes in it.

Procedure

  • Scenario: You cannot deploy a flow with one of your user-defined nodes in it.
  • Explanation: Your LIL file has failed to load.
  • Solution: Check system log (syslog or Eventviewer) of integration node startup; did you see a BIP2308 message saying a LIL file failed to load? If there are any problems loading a LIL file, a BIP2308 message appears in the system log.

You get problems when nodes try to use the ESQL path interface in the plug-in API

Procedure

  • Scenario: When you attempt to use the ESQL path interface in the plug-in API, the return value is CCI_PATH_NOT_NAVIGABLE.
  • Explanation: The plug-in API allows you to specify a path in the form of an ESQL path expression and navigate to that element, returning a handle to it if it exists. It also allows you to create elements along the path to the requested element.

    The navigate path utility function (cniSqlNavigatePath) executes the SQLPathExpression created with the cniSqlCreateReadOnlyPathExpression or cniSqlCreateModifiablePathExpression utility functions, as defined by the sqlPathExpression argument.

    If the path is not navigable, the return code is set to CCI_PATH_NOT_NAVIGABLE. This might be returned when embedding a path expression in another path expression. The input cciMessage* functions must not be NULL; however, any of the output cciMessage* functions can be NULL. If you embed a path expression that can be NULL inside a path expression that cannot be NULL, CCI_PATH_NOT_NAVIGABLE is returned.

  • Solution: If the return code is set to CCI_PATH_NOT_NAVIGABLE, ensure that if a correlation name is specified in a path, the respective parameter is not NULL.

After migration your custom property editor does not work

Procedure

  • Scenario: You have migrated to a new version of IBM® Integration Bus and your custom property editor no longer works.
  • Explanation: Custom property editors can use Eclipse or RAD APIs. If any of those APIs are changed in a new version of IBM Integration Bus, your property editor might not work.
  • Solution: Update your property editor code to comply with the changed API.

Interpreting problems in user-defined extensions

Procedure

  • Scenario: You want to debug problems in user-defined nodes and parsers.
  • Solution: Start user trace at debug level. In order to see BIP4142, BIP4144, BIP4145, and BIP4146 messages, this must be done at the integration server level. For example, use the mqsichangetrace command without the -f parameter.
    The following debug messages are available to help you to understand the execution of your user-defined nodes and parsers:
    • BIP2233 and BIP2234: a pair of messages that are traced before and after a user-defined extension implementation function is invoked. These messages report the input parameters and returned value. For example:

      BIP2233 Invoking user-defined extension function [function name] ([function call parameters])

      BIP2234 Returned from user-defined extension function [function name] with result: [result of call]
      Note: In these messages, an implementation function can be interpreted as either a C implementation function or a Java™ implementation method.
    • BIP2308: a message that is logged when the integration node fails to load a LIL file.

      BIP2308 File [name of LIL file] could not be loaded; operating system return code [error code return from operating system]

    • BIP3904: a message that is traced before invoking the Java evaluate() method of a user-defined node. For example:

      BIP3904 (for Java): Invoking the evaluate() method of node (class=[node class name], name=[label of node in flow]) where node class name is the name of the Java user-defined extension class.

    • BIP3905: a message that is traced before invoking the C cniEvaluate implementation function (iFpEvaluate member of CNI_VFT) of a user-defined node. For example:

      BIP3905 (for C): Invoking the cniEvaluate() implementation function of node (class=[node class name], name=[label of node in flow]) where node class name is the name of the user-defined extension class that is provided by the user-defined extension while calling C cniDefineNodeClass.

    • BIP4142: a debug message that is traced when invoking a user-defined node utility function, where the utility function alters the state of a syntax element. This includes all utility functions that start with cniSetElement*, where * represents all nodes with that stem. For example:

      BIP4142 Evaluating cniSetElement [element identifier type]. Changing value from [value before user's change] to [value after user's change]"

    • BIP4144 and BIP4145: a pair of messages that are traced by certain implementation functions that, when invoked by a user-defined extension, can modify the internal state of an integration node object. Possible integration node objects include syntax element, node, and parser. These messages report the input parameter provided to the invoked method and the returned value. For example:

      BIP4144 Entered function [function name] ([function call parameters])

      BIP4145 Exiting function [function name] with result: [result to be returned]

      In these messages, an implementation function can be interpreted as either a C implementation function or a Java implementation method.

      The C implementation functions that invoke messages BIP4144 and BIP4145 include:

      For user-defined parsers For user-defined nodes
      cpiCreateParserFactory cniCreateElement*
      cpiDefineParserClass cniDeleteMessage
      cpiAppendToBuffer cniAdd*
      cpiCreateElement cniDetach
      cpiCreateAndInitializeElement cniCopyElementTree
      cpiAddBefore cniFinalize
      cpiAddAfter cniWriteBuffer
      cpiAddAsFirstChild cniSql*
      cpiAddAsLastChild cniSetInputBuffer
      cpiSetNameFromBuffer cniDispatchThread

      (* represents all nodes with that stem; for example, cniAdd* includes cniAddAfter, cniAddasFirstChild, cniAddasLastChild, and cniAddBefore.)

      The Java methods that invoke messages BIP4144 and BIP4145 are:

      For user-defined nodes
      com.ibm.broker.plugin.MbElement.CreateElement*
      com.ibm.broker.plugin.MbElement.add*
      com.ibm.broker.plugin.MbElement.detach
      com.ibm.broker.plugin.MbElement.copyElementTree
    • BIP4146: a debug message that is traced when invoking a user-defined parser utility function, where the utility function alters the state of a syntax element. This includes all utility functions that start with cpiSetElement*, where * represents all nodes with that stem. For example:

      BIP4146 Evaluating cpiSetElement [element identifier type]. Changing value from [value before user's change] to [value after user's change]

      For information on the C user-defined API, see the C language user-defined parser API and the C language user-defined node API.

    • BIP4147: an error message that is traced when a user-defined extension passes an invalid input object to a user-defined extension utility API function. For Example:

      BIP4147 User-defined extension input parameter failed debug validation check. Input parameter [parameter name] passed into function [function name] is not a valid object.

    • BIP4148: an error message that is traced when a user-defined extension damages an integration node object. For Example:

      BIP4148 User-defined extension damaged an integration node object. Function [function name] has damaged integration node object passed as parameter [parameter name].

    • BIP4149: an error message that is traced when a user-defined extension passes an invalid input data pointer to a user-defined extension utility API function. For Example:

      BIP4149 User-defined extension input parameter failed debug validation check. Input parameter [parameter name] passed into function [function name] is a NULL pointer.

    • BIP4150: an error message that is traced when a user-defined extension passes invalid input data to a user-defined extension utility API function. For example:

      BIP4150 User-defined extension input parameter failed debug validation check. Input parameter [parameter name] passed into function [function name] does not have a valid value.

    • BIP4151: a debug message that is traced when cniGetAttribute2 or cniGetAttributeName2 sets the return code to an unexpected value. Expected values are CCI_SUCCESS, CCI_ATTRIBUTE_UNKNOWN, and CCI_BUFFER_TOO_SMALL. Any other value is an unexpected value. For example:

      BIP4151 An unexpected value was returned from User-defined extension implementation function [function name].

    • BIP4152: a debug message that is traced when cniGetAttribute2 or cniGetAttributeName2 sets the return code to CCI_BUFFER_TOO_SMALL, and then cniGetAttribute2 or cniGetAttributeName2 is called again, this time with the correct size buffer, however the return code is still set to CCI_BUFFER_TOO_SMALL. For example:

      BIP4152 User-defined extension Implementation function [function name] returned CCI_BUFFER_TOO_SMALL on 2nd attempt.

You want to debug classloading

Procedure

  • Scenario: You want to debug classloading.
  • Solution: Classes and the location from which they are loaded are written to user trace. Use this information to check that the correct classes are being loaded.

An error is issued when you deploy a user-defined extension on z/OS

Procedure

  • Scenario: When you deploy a user-defined extension on z/OS®, Linux®, or UNIX, an error is displayed in the log of each integration server, stating that there is insufficient authority to open the LIL file.
  • Explanation: On Linux and UNIX, the user-defined extension must have group read permission. On z/OS, the user-defined extension must have group execute permission.
  • Solution:
    • On Linux and UNIX, set the file permissions of the user-defined extension to group read by issuing the command chmod a+r.
    • On z/OS, set the file permissions of the user-defined extension to group read and execute by issuing the command chmod a+rx.

You cannot determine which user-defined extensions have been loaded by the integration node on startup

Procedure

  • Scenario: You cannot determine which user-defined extensions have been loaded by the integration node on startup.
  • Solution: Use the mqsireportproperties command for each type of user-defined extension.
    • For a Java user-defined extension, issue the command:
      mqsireportproperties IBNODE -e default -o ComIbmJavaPluginNodeFactory -r

      You see a report similar to this example: 

      ComIbmJavaPluginNodeFactory
	uuid='ComIbmJavaPluginNodeFactory'
	userTraceLevel='none'
	traceLevel='none'
	userTraceFilter='none'
	traceFilter='none'
	NodeClassName='ComIbmJMSClientInputNode'
	NodeClassName='ComIbmJMSClientOutputNode'
	NodeClassName='ComIbmJavaComputeNode'
	NodeClassName='ComIbmXslMqsiNode'
	NodeClassName='SearchFilterNode'

BIP8071I: Successful command completion.

      The user-defined extension called SearchFilter has a NodeClassName of SearchFilterNode.

    • For a C user-defined extension (assuming that CONST_PLUGIN_NODE_FACTORY was set to ComIbmSamplePluginNodeFactory in the NodeFactory.h file, as in the sample NumComputeNode), issue the command:
      mqsireportproperties IBNODE -e default -o ComIbmSamplePluginNodeFactory -r

      You see a report similar to this example:

      ComIbmSamplePluginNodeFactory
	uuid='ComIbmSamplePluginNodeFactory'
	userTraceLevel='none'
	traceLevel='none'
	userTraceFilter='none'
	traceFilter='none'
	NodeClassName='NumComputeNode'
	
BIP8071I: Successful command completion.

      The user-defined extension called NumCompute has a NodeClassName of NumComputeNode.

You are migrating a C user-defined node and cniDefineNodeClass returns CCI_INV_IMPL_FUNCTION.

Procedure

  • Scenario: When you attempt to migrate a C user-defined node, cniDefineNodeClass returns CCI_INV_IMPL_FUNCTION.
  • Explanation: New fields have been added to the CNI_VFT struct. CNI_VFT_DEFAULT has been updated to initialize these new fields in the header file BipCci.h. If you initialize your CNI_VFT with CNI_VFT_DEFAULT, you should not need to make any code changes. However, if you do not initialize CNI_VFT with CNI_VFT_DEFAULT, these new fields are initialized with random values.
  • Solution: Initialize your CNI_VFT with CNI_VFT_DEFAULT.