This topic contains sections marked as revised for this release

WebSphere Message Brokers
File: ar25255_
Writer: Cerys Giddings

Reference topic

This build: July 31, 2007 21:36:28

Restrictions on migrating message mappings

In certain scenarios, the migration of .mfmap files is not fully supported.

This topic explains why migration is not automatic in these situations, and provides instructions for how to complete a successful migration. This topic also provides information about problems migrating submaps.

The programming model for message maps is different between Version 5.0 (where the file format is .mfmap) and Version 6.1 (where the format is .msgmap). Version 5.0 message maps have a procedural programming model, which is essentially an alternative ESQL, where you describe all the steps that are required to perform a transformation. Version 6.1 uses a declarative programming model, where you describe the result of the transformation, and the tools determine how to achieve that result.

Most migration failures result from message maps that contain too much information about the steps that perform the transformation, and not enough information about the desired result. For these message maps, migration is enabled by changing the .mfmap file so that specific "how to" sections are separated into an ESQL function or procedure that can be called by the message map. The .mfmap file calls the ESQL instead of containing it as an expression. The mqsimigratemfmaps command then migrates the .mfmap file, but calls the ESQL instead of logging a migration error.

A limitation is that ESQL (the run time for .mfmap and .msgmap files) cannot define functions that return complex element (or REFERENCE) values. The following procedure explains how to work around this complex element target limitation; in many cases, you must rewrite the map as ESQL. For more examples and information about calling ESQL from maps refer to the following sample: You can view samples only when you use the information center that is integrated with the Message Brokers Toolkit.
  1. Determine whether you can define an ESQL function for the .mfmap file.
    1. When the target value is a complex element, or in ESQL terms a REFERENCE, the individual mapping must be rewritten in the .msgmap file. Delete the mapping from the .mfmap file, and proceed to Step 4.
    2. Use a function for all other cases: CHAR string, numbers, date and time. Proceed to Step 2.
  2. Determine the source parameters and returns type for your function.
    1. For each source path in the mapping, there must be one parameter in the function or procedure. For a function, all parameters are unchangeable. The type of the parameter must match the source data type.
    2. The function return type is the ESQL datatype identified above.
  3. Update the .mfmap file to enable migration. Change the .mfmap file to invoke the function in the mapping, passing the source parameters to the function in the order in which they were listed in step 2a.
  4. Re-run the mqsimigratemfmaps command to migrate the modified .mfmap file.
  5. Repeat Steps 1 to 4 until no errors are reported in the migration log.
  6. Start the Version 6.1 Message Broker Toolkit and open the migrated .msgmap file.
    1. For ESQL that is migrated as functions, there should be no errors.
    2. For complex element targets, rewrite the mapping using the Version 6.1 features.
The following examples illustrate migration of .mfmap files to .msgmap files.
  • To migrate a multiple reference to a repeating source expression:
    src_msg.e[1] + src_msg.e[2]  
    compute the result in an ESQL function like:
    CREATE FUNCTION addOneAndTwo(IN src_msg)
    BEGIN
    	RETURN src_msg.e[1] + src_msg.e[2]; 	
    END;  
    In the .msgmap file, call the ESQL function addOneAndTwo using the parent element src_msg as a parameter.

  • An expression that does not use element names:
    src_msg.* 
    or
    src_msg.*[]  	
    can be processed using a function that takes the parent of the repeating field:
    CREATE FUNCTION processAny(IN src_msg)  	
    BEGIN 		
    	DECLARE nodeRef REFERENCE TO src_msg.e.*; 		
    	DECLARE result <dataType> <initialValue>;
    	WHILE LASTMOVE nodeRef DO 			
    		--expression goes here 			
    		SET result = result; 		
    	END WHILE; 		
    	RETURN RESULT; 	
    END;  
    In the .msgmap file, call the ESQL function using the parent element src_msg as a parameter.

  • Expressions that dynamically compute element names:
    src_msg.{'a' || 'b'}  
    can be processed by ESQL functions that process the parent of the repeating field:
    CREATE FUNCTION processDynamicName(IN src_msg)  	
    BEGIN 		
    	RETURN src_msg.{'a' || 'b'}; 	
    END;  
    In the .msgmap file, call the ESQL function using the parent element src_msg as a parameter.

  • Expressions that use the select MIN, MAX, and COUNT functions:
    SELECT MAX("#T".FIRSTNAME)  		
    	FROM Database.CUSTOMER AS "#T"  		
    	WHERE "#T".CUSTOMERID = custId  
    can be processed by ESQL functions that process the parent of the repeating field:
    CREATE FUNCTION processMAX(IN custId)  	
    BEGIN 		
    	RETURN  			
    	SELECT MAX("#T".FIRSTNAME) 				
    		FROM Database.CUSTOMER AS "#T" 				
    		WHERE "#T".CUSTOMERID = custId 	
    END;  
    In the .msgmap file, call the ESQL function using the element custId as a parameter.

  • .mfmap files that use mfmap index variables in expressions:
    e || "#I"  
    must be rewritten entirely in ESQL. By definition, there must be a complex repeating parent element, and this is not supported by ESQL functions.

  • Expressions that use source expressions to compute values:
    src_msg.e[src_msg.a]  
    must be rewritten using if rows, msgmap:occurrence() functions, and ESQL functions:
    for src_msg.e 		
    	if 			
    		condition msgmap:occurrence(src_msg/e) = src_msg/a 

  • For expressions that use index expressions to compute values:
    src_msg.e["#I" +5] 	
    src_msg.e[< 3]  
    the entire .msgmap file must be rewritten in ESQL, because the .msgmap files do not support indexed access to repeating fields.

  • .mfmap files that use ROW expressions to compute values:
    src_msg.e IN (1, 2, 3)  
    must be rewritten in ESQL, because .msgmap files do not support ESQL ROW expressions.

Restrictions on migrating submaps

In Version 5.0 message maps, any complex element type can be a root of a submap. However, in Version 6.1, only a global element or a global attribute can be the root of a submap. When a Version 5.0 message map with a call to a submap with a non-global element as the map root is migrated, the submap is not migrated as a standalone submap. Instead, the call to the submap in the main message map is replaced by the migrated content of the submap. Alternatively, if the submap has a global element as the map root, the submap is migrated to a standalone Version 6.1 submap instead.

For Version 6.1, reusable schema structures must be defined as global elements and types. If you have Version 5.0 submaps that use local elements, you must change the schema to add definitions of global elements for the local elements, and then use the new schema after migration. If the new global elements have the same name and type as the local elements, then the Version 5.0 submaps do not need to be changed.

A local element in a Version 5.0 submap must be qualified with a namespace in order to be successfully migrated to Version 6.1, because the global element that replaces the it on migration must be qualified by the namespace. If your submap contains local elements, then you must re-create the submap and re-create the call to the submap from the main message map.

The following table shows differences between the features that are supported in a submap for Version 5.0 and Version 6.1.
Version Supported feature
Version 5.0 global elements and global attributes as map source
global elements and global attributes as map target
local elements and local attributes as map source
local elements and local attributes as map target
Version 6.1 global elements, global attributes and global types as map source
global elements and global attributes as map target
Related tasks
Developing ESQL
Related reference
Migrating message mappings from Version 5.0
mqsimigratemfmaps command
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:36:28

ar25255_ This topic's URL is: