com.ibm.ims.application
Class IMSFieldMessage

java.lang.Object
  |
  +--com.ibm.ims.base.DLIBaseSegment
        |
        +--com.ibm.ims.application.IMSFieldMessage
All Implemented Interfaces:
java.lang.Cloneable, java.io.Serializable

public abstract class IMSFieldMessage
extends DLIBaseSegment

IMSFieldMessage is an abstract base class for objects representing a message either comming from and going to an IMS message queue. A subclassed IMSFieldMessage provides a mapping between the data contained in the message and access functions that operate on the class. User applications can reference individual fields of the message by either field index or field name utilizing a wide range of data conversion functions provided by the base class DLIBaseSegment.

To create this mapping, a subclass must provide an array of DLITypeInfo objects representing the fields of the message as the argument in the IMSFieldMessage constructor. By doing so, the DLIBaseSegment class learns the layout of each field in the message which then allows the user to easily access as well as update each of these fields.

IMSFieldMessage is used to define either normal input and output messages (usually a separate subclass for each) or to define a Scratch Pad Area (SPA). The SPA is used in conversational transactions to store information between steps in the conversation. To define a SPA message, the IMSFieldMessage subclass must set the isSPA argument in the IMSFieldMessage constructor to true.

IMPORTANT NOTE: Fields of type CHAR or VARCHAR will be encoded using the platform's default character encoding. If another encoding is desired, invoke the inherited setDefaultEncoding method of the IMSFieldMessage class. This method is used to specify the character encoding for all character data in a the message. A typical IMSFieldMessage subclass for an input message will look similar to the following:

 public class InputMessage extends com.ibm.ims.application.IMSFieldMessage {
    static final DLITypeInfo[] segmentInfo = {
      new DLITypeInfo("Field1", DLITypeInfo.CHAR,      1, 10), 
      new DLITypeInfo("Field2", DLITypeInfo.INTEGER,  11,  4),
      new DLITypeInfo("Field3", DLITypeInfo.SMALLINT, 15,  2)
    };

    public MySegment() {
       super(segmentInfo, 16, false);

       // can set the default character encoding to be used here for all character data
       // in this segment, otherwise it will default to the system's default encoding

       // this.setDefaultEncoding("UTF8");
    }
 }   
 
Code to access the fields in InputMessage will look similar to the following:
 InputMessage inputMessage = new InputMessage();
 messageQueue.getUniqueMessage(inputMessage);
 
 // Return "Field1" as a String using its index                                            
 String field1 = inputMessage.getString(1);  
 
 // Return "Field2" as a String using its field name (note: int to String conversion) 
 String field2 = inputMessage.getString("Field2");
 

See Also:
DLIBaseSegment, DLITypeInfo, IMSMessageQueue, Serialized Form

Field Summary
static short MAX_MESSAGE_LENGTH
          The maximum size of the body of a message.
static int TRANSCODE_FIXED_8
          The transaction code rule indicating that any transaction code will be padded with blanks to a total of 8 bytes in length before the message body begins.
static int TRANSCODE_FIXED_9
          The transaction code rule indicating that any transaction code will be padded with blanks to a total of 9 bytes in length before the message body begins.
static int TRANSCODE_VAR_8
          The transaction code rule indicating that exactly one blank will be present between the transaction code and the message body if the transaction code is less than 8 bytes in length.
static int TRANSCODE_VAR_9
          The transaction code rule indicating that exactly one blank will always be present between the transaction code and the message body.
 
Fields inherited from class com.ibm.ims.base.DLIBaseSegment
ioArea, ioAreaLength, ioAreaOffset
 
Constructor Summary
IMSFieldMessage(DLITypeInfo[] typeInfo, int length, boolean isSPA)
          Creates a new IMSFieldMessage with the specified message length.
IMSFieldMessage(DLITypeInfo[] typeInfo, int length, boolean isSPA, byte[] ioArea, int transCodeRule)
          Creates a new IMSFieldMessage with the specified message length.
IMSFieldMessage(DLITypeInfo[] typeInfo, int length, boolean isSPA, int transCodeRule)
          Creates a new IMSFieldMessage with the specified message length.
IMSFieldMessage(IMSFieldMessage message, DLITypeInfo[] typeInfo)
          Creates a new IMSFieldMessage from an existing IMSFieldMessage.
 
Method Summary
 void clearBody()
          Clear out the message body with " ".
 void clearWarnings()
          Clears the warning chain for this IMSFieldMessage.
 byte[] getBytes()
          Returns the raw byte array of the message field.
 int getMessageLength()
          Return the length of this message.
 java.lang.String getTransactionID()
          Returns the transaction ID for the input message after being read off the message queeue by IMSMessageQueue.
 DLIWarning getWarnings()
          The first warning reported by calls on this IMSFieldMessage is returned.
protected  void setBytes(byte[] ioArea)
          Sets the field indicated by the index to the exact bytes passed in the array, with no conversion.
static void setTransCodeRule(int rule)
          Sets the transaction code rule for this message.
 
Methods inherited from class com.ibm.ims.base.DLIBaseSegment
clone, getBigDecimal, getBigDecimal, getBigDecimal, getBigDecimal, getBoolean, getBoolean, getByte, getByte, getBytes, getBytes, getDate, getDate, getDefaultEncoding, getDouble, getDouble, getFloat, getFloat, getInt, getInt, getLong, getLong, getOffset, getSegmentName, getShort, getShort, getString, getString, getTime, getTime, getTimestamp, getTimestamp, getTypeInfo, getTypeInfo, getTypeInfo, setBigDecimal, setBigDecimal, setBoolean, setBoolean, setByte, setByte, setBytes, setBytes, setDate, setDate, setDefaultEncoding, setDouble, setDouble, setFloat, setFloat, setInt, setInt, setLong, setLong, setShort, setShort, setString, setString, setTime, setTime, setTimestamp, setTimestamp
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MAX_MESSAGE_LENGTH

public static final short MAX_MESSAGE_LENGTH
The maximum size of the body of a message.

TRANSCODE_VAR_8

public static final int TRANSCODE_VAR_8
The transaction code rule indicating that exactly one blank will be present between the transaction code and the message body if the transaction code is less than 8 bytes in length. If the transaction code is exactly 8 bytes in length, the message body will immediately follow.

TRANSCODE_VAR_9

public static final int TRANSCODE_VAR_9
The transaction code rule indicating that exactly one blank will always be present between the transaction code and the message body. If the transaction code is exactly 8 bytes in length, the ninth byte will be a blank.

TRANSCODE_FIXED_9

public static final int TRANSCODE_FIXED_9
The transaction code rule indicating that any transaction code will be padded with blanks to a total of 9 bytes in length before the message body begins.

TRANSCODE_FIXED_8

public static final int TRANSCODE_FIXED_8
The transaction code rule indicating that any transaction code will be padded with blanks to a total of 8 bytes in length before the message body begins.
Constructor Detail

IMSFieldMessage

public IMSFieldMessage(DLITypeInfo[] typeInfo,
                       int length,
                       boolean isSPA)
                throws java.lang.IllegalArgumentException
Creates a new IMSFieldMessage with the specified message length. The maximum length is limited to MAX_MESSAGE_LENGTH (32750) bytes.
Parameters:
typeInfo - The array of DLITypeInfo objects defining the fields in the message.
length - The length for the message body of this message.
isSPA - Flag indicating whether this message is a SPA message
Throws:
java.lang.IllegalArgumentException - if the length is invalid

IMSFieldMessage

public IMSFieldMessage(DLITypeInfo[] typeInfo,
                       int length,
                       boolean isSPA,
                       int transCodeRule)
                throws java.lang.IllegalArgumentException
Creates a new IMSFieldMessage with the specified message length. The maximum length is limited to MAX_MESSAGE_LENGTH (32750) bytes.
Parameters:
typeInfo - The array of DLITypeInfo objects defining the fields in the message.
length - The length for the message body of this message.
isSPA - Flag indicating whether this message is a SPA message
transCodeRule - the trans code rule used
Throws:
java.lang.IllegalArgumentException - if the length is invalid

IMSFieldMessage

public IMSFieldMessage(DLITypeInfo[] typeInfo,
                       int length,
                       boolean isSPA,
                       byte[] ioArea,
                       int transCodeRule)
                throws java.lang.IllegalArgumentException
Creates a new IMSFieldMessage with the specified message length. The maximum length is limited to MAX_MESSAGE_LENGTH (32750) bytes.
Parameters:
typeInfo - The array of DLITypeInfo objects defining the fields in the message.
length - The length for the message body of this message.
isSPA - Flag indicating whether this message is a SPA message
ioArea - the input byte array
transCodeRule - the trans code rule used
Throws:
java.lang.IllegalArgumentException - if the length is invalid

IMSFieldMessage

public IMSFieldMessage(IMSFieldMessage message,
                       DLITypeInfo[] typeInfo)
Creates a new IMSFieldMessage from an existing IMSFieldMessage. This allows an application to define one message that contains definitions of fields common to any input message and use that message to construct similar messages that define the remaining fields. The following code demonstrates how this can be used to define three messages that have the field 'CommandCode' in common.
	public class LogicalBaseMessage extends IMSFieldMessage {
		final static DLITypeInfo[] typeInfo = {
			new DLITypeInfo("CommandCode", DLITypeInfo.CHAR, 1, 20),
		}

		public LogicalBaseMessage() {
			super(typeInfo, 30, false);
		}
	}
	
	public class LogicalSublcassA extends IMSFieldMessage {
		final static DLITypeInfo[] typeInfo = {
			new DLITypeInfo("CommandCode", DLITypeInfo.CHAR, 1,  20),
			new DLITypeInfo("SomeFieldA",  DLITypeInfo.CHAR, 21, 10),
		}

		public LogicalSubclassA(IMSFieldMessage message) {
			super(message, typeInfo);
		}
	}
 
	public class LogicalSubclassB extends IMSFieldMessage {
		final static DLITypeInfo[] typeInfo = {
			new DLITypeInfo("CommandCode", DLITypeInfo.CHAR, 1,  20),
			new DLITypeInfo("SomeFieldB",  DLITypeInfo.CHAR, 21, 5),
		}

		public LogicalSubclassB(IMSFieldMessage message) {
			super(message, typeInfo);
		}
	}
 
Notice a few points about the preceding code: 1. The 'CommandCode' field is defined within every class. This is really only necessary if users of LogicalSubclassA and LogicalSubclassB require access to this field. 2. The length of the "logical" base class, LogicalBaseClass, must be large enough to contain any of its "logical" subclasses. Therefore, LogicalBaseClass is 30 bytes long because the fields of LogicalSubclassA require it. 3. Each "logical" subclass must provide a constructor to create itself from another IMSFieldMessage. Given this approach, an application can provide message reading logic similar to the following:
	LogicalBaseClass inputMessage = new LogicalBaseClass();
	while(messageQueue.getUniqueMessage(inputMessage)) {
		String commandCode = inputMessage.getString("CommandCode").trim();
		if (commandCode.equals("LogicalSubclassA")) {
			processA(new LogicalSubclassA(inputMessage));
		}
		else if (commandCode.equals("LogicalSubclassB")) {
			processB(new LogicalSubclassB(inputMessage));
		}
		else {
			// process an error
		}
	}
	
Parameters:
message - the IMSFieldMessage, or "logical" base class, that this message can be created from
typeInfo - the array of DLITypeInfo objects defining the fields in the message
Method Detail

clearBody

public void clearBody()
Clear out the message body with " ". This will reset all CHAR data fields to blanks, yet leave all non-CHAR fields with 0x40 (if EBCDIC) 0x20 (if ASCII) data. This can cause potential problems for ZONEDDECIMAL and PACKEDDECIMAL since any 'get' access to that field will throw a DLIException given that it will look for a sign trailing byte of which the " " is invalid. To correct for this problem make sure that following a clearBody, a 'set' command is issued to any PACKEDDECIMAL or ZONEDDECIMAL field before any 'get' command.

clearWarnings

public void clearWarnings()
Clears the warning chain for this IMSFieldMessage. After this call getWarnings returns null until a new warning is reported for this IMSFieldMessage.
Overrides:
clearWarnings in class DLIBaseSegment

getBytes

public byte[] getBytes()
Returns the raw byte array of the message field. This byte array includes the LL and ZZ fields, the transaction code and the message data.
Overrides:
getBytes in class DLIBaseSegment
Returns:
the byte array containing the LL and ZZ fields, the transaction code and the message data.

getMessageLength

public int getMessageLength()
Return the length of this message. This applies to the message body only, which excludes the length for the header of the message.
Returns:
the length of the message body

getTransactionID

public java.lang.String getTransactionID()
Returns the transaction ID for the input message after being read off the message queeue by IMSMessageQueue.
Returns:
the transaction ID or null if the transaction ID is not present for this message.

getWarnings

public DLIWarning getWarnings()
The first warning reported by calls on this IMSFieldMessage is returned. Subsequent warnings will be chained to this DLIWarning. The warning chain is automatically cleared each time a new message is read from the queue. Note: This warning chain only covers warnings caused by IMSFieldMessage methods.
Overrides:
getWarnings in class DLIBaseSegment
Returns:
the first DLIWarning or null

setTransCodeRule

public static final void setTransCodeRule(int rule)
                                   throws java.lang.IllegalArgumentException
Sets the transaction code rule for this message. Valid rules are TRANSCODE_VAR_8, TRANSCODE_FIXED_9, TRANSCODE_VAR_9, and TRANSCODE_FIXED_8 (default). The transaction code rule is used to determine the start of the message body when processing an input message.
Parameters:
rule - - the transaction code rule for this message

setBytes

protected void setBytes(byte[] ioArea)
Description copied from class: DLIBaseSegment
Sets the field indicated by the index to the exact bytes passed in the array, with no conversion. The index parameter is the index of the desired field that was passed to the constructor in the DLITypeInfo array. The index is one based. For example, if the fields in the segment were added to the DLITypeInfo array in order, then the first field in the segment would be index 1, the second index 2, and so on.
Overrides:
setBytes in class DLIBaseSegment
Following copied from class: com.ibm.ims.base.DLIBaseSegment
Parameters:
index - the 1-based index of the desired field in the DLITypeInfo array
value - the new value for the field


(C) International Business Machines Corporation 2004. All rights reserved.