Restrictions on migrating message mappings

There are certain scenarios where the migration of .mfmap files is not supported. This topic explains why migration is not automatic in these situations, and provides instructions for how to complete a successful migration.

The programming model for message maps is different between Version 5.0 (where the file format is .mfmap) and Version 6.0 (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.0 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, it means that the map must be rewritten as ESQL. For more examples and information about calling ESQL from maps, see the WebSphere Message Brokers mapping sample at Help > Samples Gallery > Technology samples > Message Brokers > Message Map.

  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 there are no errors in the migration log.
  6. Start the Version 6.0 Message Brokers 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.0 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 .mfmap file must be rewritten in ESQL, because the .msgmap files do not yet 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.
Related tasks
Developing ESQL
Related reference
mqsimigratemfmaps command
Migration of message mappings from Version 5.0