Input and output message formats

You must consider the platforms where your target host application and the Java™ client run, and any special characteristics your input and output message might have when you develop an application that uses the IMS TM resource adapter.

The Java application that you create is running on a different platform (for example, Windows, AIX®, and Solaris) than the enterprise information system (EIS) platform. IMS Transaction Manager (IMS TM) is an IMS application program on z/OS®). Because of the platform differences, you must convert the text data in your messages from text data in UNICODE at the client end to text data in EBCDIC that is used by your IMS application.

Depending on the Endian value for the platform where the target host application runs, and the code page that is used by your IMS host system, format conversion might be required. The default is US English (037).

Recommendation: Let the integrated development environment (IDE) handle the format conversion for you. For example, the J2C wizard in various WebSphere® or Rational® development environment creates Java data bindings from imported C, COBOL, and PL/I data structures. The data bindings do all the format conversion for your messages at run time. These data bindings are created based on the options that you select in the Importer wizard.

IMS requires that all transaction messages be prefixed by a 2-byte LL field, a 2-byte ZZ field, followed by the transaction code. The LL field specifies the length of the message. The ZZ is a field of binary zero. When you build input messages to IMS, you must set the LL value to the size of the input message, and set zz to 0.

Multi-segment and variable length output

If the IMS application returns multi-segment output or output with variable lengths, you can use the COBOL definition OUTPUT-MSG to define the output of the transaction, or create an output message for the output of the transaction.

In the following COBOL application, the output message returned by IMS consists of three fixed-length segments. The total output message returned by this IMS application is a fixed size of 99 bytes and is represented by the COBOL 01 structure OUTPUT-MSG. OUTPUT-SEG1 is 16 bytes in length, OUTPUT-SEG2 is 31 bytes, and OUTPUT-SEG3 is 52 bytes.

LINKAGE SECTION.
		                                                   
	        01  INPUT-MSG.                                                     
	            02  IN-LL          PICTURE S9(3) COMP.                         
	            02  IN-ZZ          PICTURE S9(3) COMP.                         
	            02  IN-TRCD        PICTURE X(5).                               
	            02  IN-DATA1       PICTURE X(6).
	            02  IN-DATA2       PICTURE X(6).
							  
	        01  OUTPUT-MSG.                                                   
	            02  OUT-ALLSEGS  PICTURE X(99) VALUE SPACES.
	
	        01  OUTPUT-SEG1.
	            02  OUT-LL       PICTURE S9(3) COMP VALUE +0.                 
	            02  OUT-ZZ       PICTURE S9(3) COMP VALUE +0.                  
	            02  OUT-DATA1    PICTURE X(12) VALUE SPACES.
	
	        01  OUTPUT-SEG2.
	            02  OUT-LL       PICTURE S9(3) COMP VALUE +0.                 
	            02  OUT-ZZ       PICTURE S9(3) COMP VALUE +0.                  
	            02  OUT-DATA1    PICTURE X(13) VALUE SPACES.
	            02  OUT-DATA2    PICTURE X(14) VALUE SPACES.
	
	        01  OUTPUT-SEG3.
	            02  OUT-LL       PICTURE S9(3) COMP VALUE +0.                  
	            02  OUT-ZZ       PICTURE S9(3) COMP VALUE +0.                  
	            02  OUT-DATA1    PICTURE X(15) VALUE SPACES.
	            02  OUT-DATA2    PICTURE X(16) VALUE SPACES.
	            02  OUT-DATA3    PICTURE X(17) VALUE SPACES.

You can use the J2C wizard to create a J2C bean that runs the IMS transaction by :

Creating a message buffer class to store the output message returned from the IMS application
Importing the COBOL file to do the COBOL-to-Java mapping for both the input and output messages
- Creating the input binding operation by selecting the input message structure (represented by the COBOL 01 structure INPUT-MSG)
- Creating the output binding operations for the segments of the output message by using the data mapping wizard, available by selecting File > New > Other > CICS/IMS Java Data Binding. For each segment, use the data binding wizard to select the correct segment as the data structure and specify the parameters such as the code page, endian name, quote name, and trunc name.
Invoking the J2C bean method that runs the IMS transaction, and populating the output segments from the buffer of data returned by the IMS transaction

package sample.ims;

import com.ibm.etools.marshall.util.MarshallIntegerUtils;
import sample.ims.data.*;

public class TestMultiSeg
{
	public static void main (String[] args)
	{
		byte[] segBytes = null;
		int srcPos = 0;
		int dstPos = 0;
		int totalLen = 0;
		int remainLen = 0;
		byte[] buff;
		short LL = 0;
		short ZZ = 0;

		try
		{
			// ---------------------------------------------------			
			// Populate the IMS transaction input message with
			// data.  Use the input message format handler method 
			// getSize() to set the LL field of the input message.
			// ---------------------------------------------------					
			InputMsg input = new InputMsg();
			input.setIn__ll((short) input.getSize());
			input.setIn__zz((short) 0);
			//----------------------------------------------
			// find out the transaction code from your IMS 
			// administrator
			//-----------------------------------------------
			input.setIn__trcd("SKS6 ");
			input.setIn__data1("M2 SI1");
			input.setIn__data2("M3 SI1");

			// ---------------------------------------------------			
			// Run the IMS transaction.  The multi-segment output 
			// message is returned.
			// ---------------------------------------------------				
			MSOImpl proxy = new MSOImpl();
			
			sample.ims.CCIBuffer output = proxy.runMultiSegOutput(input);

			// ---------------------------------------------------	
			// Retrieve the multi-segment output message as a 
			// byte array using the output message format
			// handler method getBytes().
			// ---------------------------------------------------			 			
			System.out.println(
				"\nSize of output message is: " + output.getSize());
			segBytes = output.getBytes();

			srcPos = 0;
			dstPos = 0;
			totalLen = segBytes.length;
			remainLen = totalLen;

			// ---------------------------------------------------	
			// Populate first segment object from buffer. 
			// ---------------------------------------			             
			buff = null;
			// Get length of segment.
			LL =
				MarshallIntegerUtils.unmarshallTwoByteIntegerFromBuffer(
					segBytes,
					srcPos,
					true,
					MarshallIntegerUtils.SIGN_CODING_TWOS_COMPLEMENT);

			// Put segment in byte array.
			buff = new byte[LL];
			System.arraycopy(segBytes, srcPos, buff, dstPos, LL);
			remainLen -= LL;

			// Create and populate segment object from byte array.
			OutputSeg1 S1 = new OutputSeg1();
			S1.setBytes(buff);
			System.out.println(
				"\nOutSeg1 LL is:    "
					+ S1.getOut__ll()
					+ "\nOutSeg1 ZZ is:    "
					+ S1.getOut__zz()
					+ "\nOutSeg1_DATA1 is: "
					+ S1.getOut__data1());

			// ---------------------------------------------------	
			// Populate second segment object from buffer. 
			// ---------------------------------------------------	
			srcPos += LL;
			buff = null;
			// Get length of segment.
			LL =
				MarshallIntegerUtils.unmarshallTwoByteIntegerFromBuffer(
					segBytes,
					srcPos,
					true,
					MarshallIntegerUtils.SIGN_CODING_TWOS_COMPLEMENT);

			// Put segment in byte array.
			buff = new byte[LL];
			System.arraycopy(segBytes, srcPos, buff, dstPos, LL);
			remainLen -= LL;

			// Create and populate segment object from byte array.
			
			OutputSeg2 S2 = new OutputSeg2();
			S2.setBytes(buff);
			System.out.println(
				"\nOutSeg2 LL is:    "
					+ S2.getOut__ll()
					+ "\nOutSeg2 ZZ is:    "
					+ S2.getOut__zz()
					+ "\nOutSeg2_DATA1 is: "
					+ S2.getOut__data1()
					+ "\nOutSeg2_DATA2 is: "
					+ S2.getOut__data2());
			// ---------------------------------------------------				
			// Populate third segment object from buffer. 
			// ---------------------------------------------------	
			srcPos += LL;
			buff = null;
			// Get length of segment.
			LL =
				MarshallIntegerUtils.unmarshallTwoByteIntegerFromBuffer(
					segBytes,
					srcPos,
					true,
					MarshallIntegerUtils.SIGN_CODING_TWOS_COMPLEMENT);

			// Put segment in byte array.
			buff = new byte[LL];
			System.arraycopy(segBytes, srcPos, buff, dstPos, LL);
			remainLen -= LL;

			// Create and populate segment object from byte array.
			OutputSeg3 S3 = new OutputSeg3();
			S3.setBytes(buff);
			System.out.println(
				"\nOutSeg3 LL is:    "
					+ S3.getOut__ll()
					+ "\nOutSeg3 ZZ is:    "
					+ S3.getOut__zz()
					+ "\nOutSeg3_DATA1 is: "
					+ S3.getOut__data1()
					+ "\nOutSeg3_DATA2 is: "
					+ S3.getOut__data2()
					+ "\nOutSeg3_DATA3 is: "
					+ S3.getOut__data3());
		}
		catch (Exception e)
		{
			System.out.println("\nCaught exception is: " + e);
		}
	}
}

For variable length messages, multiple segment messages, and messages that contain arrays, see the IMS tutorials and samples in the online help or IBM® Documentation in the WebSphere or Rational development environment.

IMS tutorials are available in Tutorials > Do and Learn.
IMS samples are available in Samples > Technology samples > J2C samples.

These tutorials and samples provide guidance information and sample code for handling special message formats.