IMSFieldMessage

java.lang.Object
- com.ibm.ims.base.DLIBaseSegment
- - com.ibm.ims.application.IMSFieldMessage

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable
```
public abstract class IMSFieldMessage
extends com.ibm.ims.base.DLIBaseSegment
```
IMSFieldMessage is an abstract base class to represent input and output messages for IMS message queues interactions. 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 are 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 the message. A typical IMSFieldMessage subclass for an input message looks 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");
    }
 }   
 
 
```
The following sample code shows how to access fields in IOMessage.
```
 
 InputMessage inputMessage = new InputMessage();
 messageQueue.getUniqueMessage(inputMessage);
 
 // Return "Field2" as a String using its field name (note: int to String conversion) 
 String field2 = inputMessage.getString("Field2");
 
 
```
See Also:

DLIBaseSegment, DLITypeInfo, Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`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_FIXED_BLKREQD` The transaction code rule indicating that any transaction code will be fixed 8 bytes, always padded with a blank space before the message body begins.
`static int`	`TRANSCODE_FIXED_NOBLANK` The transaction code rule indicating that any transaction code will be fixed 8 bytes immediately followed by the message body begins.
`static int`	`TRANSCODE_NONE` The transaction code rule indicating that there is no transaction code before the start of the message body.
`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.

Constructor Summary

Constructors
Constructor and Description
`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

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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.
`boolean`	`getIsSPAMessage()`
`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`.
`int`	`getTransCodeRule()`
`com.ibm.ims.dli.DLIWarning`	`getWarnings()` The first warning reported by calls on this IMSFieldMessage is returned.
`void`	`setTransactionID(java.lang.String transactionID)` Sets the transaction ID in the SPA message.
`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, 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.
    
    See Also:
    
    Constant Field Values
  - 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.
    
    See Also:
    
    Constant Field Values
  - 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.
    
    See Also:
    
    Constant Field Values
  - 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.
    
    See Also:
    
    Constant Field Values
  - 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.
    
    See Also:
    
    Constant Field Values
  - TRANSCODE_FIXED_BLKREQD
```
public static final int TRANSCODE_FIXED_BLKREQD
```
    The transaction code rule indicating that any transaction code will be fixed 8 bytes, always padded with a blank space before the message body begins.
    
    See Also:
    
    Constant Field Values
  - TRANSCODE_FIXED_NOBLANK
```
public static final int TRANSCODE_FIXED_NOBLANK
```
    The transaction code rule indicating that any transaction code will be fixed 8 bytes immediately followed by the message body begins.
    
    See Also:
    
    Constant Field Values
  - TRANSCODE_NONE
```
public static final int TRANSCODE_NONE
```
    The transaction code rule indicating that there is no transaction code before the start of the message body.
    
    See Also:
    
    Constant Field Values
- 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.
  - getIsSPAMessage
```
public boolean getIsSPAMessage()
```
  - 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 com.ibm.ims.base.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 com.ibm.ims.base.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.
  - setTransactionID
```
public void setTransactionID(java.lang.String transactionID)
                      throws DLIException
```
    Sets the transaction ID in the SPA message. This is used for deferred program switching.
    
    Throws:
    
    DLIException
  - getWarnings
```
public com.ibm.ims.dli.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 com.ibm.ims.base.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
    
    Throws:
    
    java.lang.IllegalArgumentException
  - getTransCodeRule
```
public int getTransCodeRule()
```

Class IMSFieldMessage

Field Summary

Constructor Summary

Method Summary

Methods inherited from class com.ibm.ims.base.DLIBaseSegment

Methods inherited from class java.lang.Object

Field Detail

MAX_MESSAGE_LENGTH

TRANSCODE_VAR_8

TRANSCODE_VAR_9

TRANSCODE_FIXED_9

TRANSCODE_FIXED_8

TRANSCODE_FIXED_BLKREQD

TRANSCODE_FIXED_NOBLANK

TRANSCODE_NONE

Constructor Detail

IMSFieldMessage

IMSFieldMessage

IMSFieldMessage

IMSFieldMessage

Method Detail

clearBody

getIsSPAMessage

clearWarnings

getBytes

getMessageLength

getTransactionID

setTransactionID

getWarnings

setTransCodeRule

getTransCodeRule