com.ibm.as400.access

Class RecordFormat

  • java.lang.Object
    • com.ibm.as400.access.RecordFormat
  • All Implemented Interfaces:
    java.io.Serializable

    public class RecordFormat
extends java.lang.Object
implements java.io.Serializable
    The RecordFormat class represents the format of data returned from an IBM i system. It contains FieldDescription objects that describe the data returned from a system. The RecordFormat class is used to generate a Record object that can be used to access the data returned from the system as Java objects or as byte arrays of IBM i data. For instance, the entries on a data queue may have a specific format. This format could be represented by a RecordFormat object. The RecordFormat object could be used to generate a Record object containing the data read from the data queue. Based on the description of the data contained in the RecordFormat object, the Record object could be used by the Java program to handle the data as Java objects. As another example, a parameter for a program may be an array of bytes representing several different types of data. Such a parameter could be described by a RecordFormat object.

    The RecordFormat class is also used to describe the record format of a file when using the record-level database access classes. The record format of the file must be set prior to invoking the open() method on an AS400File object.

    The RecordFormat class is also used to describe the record format of a record when using the LineDataRecordWriter class. The following record format attributes are required to be set.

    • Record format ID
    • Record format type
    • Field descriptions that make up the record format
    • The delimiter, when the record format type is VARIABLE_LAYOUT_LENGTH
    • Field description layout attributes,length and alignment, when the record format is FIXED_LAYOUT_LENGTH

    The RecordFormat class allows the user to do the following:

    • Describe the data returned from a system.
    • Retrieve a Record object containing data that is described by the RecordFormat.
    RecordFormat objects generate the following events:
    • RecordDescriptionEvent
      The events fired are:
      • fieldDescriptionAdded()
      • keyFieldDescriptionAdded()
    • PropertyChangeEvent
    • VetoableChangeEvent
    Examples
    See Also:
    AS400FileRecordDescription, Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field and Description
      static int FIXED_LAYOUT_LENGTH
      This constant is only used for record level writing.
      static int VARIABLE_LAYOUT_LENGTH
      This constant is only used for record level writing.

    • Constructor Summary

      Constructors 
      Constructor and Description
      RecordFormat()
      Constructs a RecordFormat object.
      RecordFormat(java.lang.String name)
      Constructs a RecordFormat object.

    • Method Summary

      Methods 
      Modifier and Type Method and Description
      void addFieldDescription(FieldDescription field)
      Adds a field description to this record format.
      void addKeyFieldDescription(int index)
      Adds a key field description to this record format.
      void addKeyFieldDescription(java.lang.String name)
      Adds a key field description to this record format.
      void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
      Adds a listener to be notified when the value of any bound property is changed.
      void addRecordDescriptionListener(RecordDescriptionListener listener)
      Adds a listener to be notified when a RecordDescriptionEvent is fired.
      void addVetoableChangeListener(java.beans.VetoableChangeListener listener)
      Adds a listener to be notified when the value of any constrained property is changed.
      char getDelimiter()
      Returns the delimiter.
      FieldDescription getFieldDescription(int index)
      Returns the field description at the specified index.
      FieldDescription getFieldDescription(java.lang.String name)
      Returns the field description with the specified name.
      FieldDescription[] getFieldDescriptions()
      Returns the field descriptions that make up this object.
      java.lang.String[] getFieldNames()
      Returns the names of the field descriptions that make up this record format.
      int getIndexOfFieldName(java.lang.String name)
      Returns the index of the field description named name.
      int getIndexOfKeyFieldName(java.lang.String name)
      Returns the index of the field description of the key field named name.
      FieldDescription getKeyFieldDescription(int index)
      Returns the field description of the key field at the specified index.
      FieldDescription getKeyFieldDescription(java.lang.String name)
      Returns the field description of the key field with the specified name.
      FieldDescription[] getKeyFieldDescriptions()
      Returns the key field descriptions that make up this object.
      java.lang.String[] getKeyFieldNames()
      Returns the names of the field descriptions of the keys that make up this record format.
      int getLengthDependency(int index)
      Returns the index of the field description on which the field description at the specified index depends.
      int getLengthDependency(java.lang.String name)
      Returns the index of the field description on which the field description with the specified name depends.
      java.lang.String getName()
      Returns the name of this record format.
      Record getNewRecord()
      Returns a new record based on this record format, which contains default values for the contents of the fields.
      Record getNewRecord(byte[] contents)
      Returns a new record based on this record format, which contains data from the specified byte array.
      Record getNewRecord(byte[] contents, int offset)
      Returns a new record based on this record format, which contains data from the specified byte array.
      Record getNewRecord(byte[] contents, int offset, java.lang.String recordName)
      Returns a new record based on this record format, which contains data from the specified byte array.
      Record getNewRecord(byte[] contents, java.lang.String recordName)
      Returns a new record based on this record format, which contains data from the specified byte array.
      Record getNewRecord(java.lang.String recordName)
      Returns a new record based on this record format, which contains default values for the contents of the fields.
      int getNumberOfFields()
      Returns the number of field descriptions in this record format.
      int getNumberOfKeyFields()
      Returns the number of key field descriptions in this record format.
      int getOffsetDependency(int index)
      Returns the index of the field description on which the field description at the specified index depends.
      int getOffsetDependency(java.lang.String name)
      Returns the index of the field description on which the field description with the specified name depends.
      java.lang.String getRecordFormatID()
      Returns the record format ID.
      int getRecordFormatType()
      Returns the record format type.
      void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
      Removes a listener from the change list.
      void removeRecordDescriptionListener(RecordDescriptionListener listener)
      Removes a listener from the record description listeners list.
      void removeVetoableChangeListener(java.beans.VetoableChangeListener listener)
      Removes a listener from the veto change listeners list.
      void setDelimiter(char delimiter)
      Sets the delimiter.
      void setLengthDependency(int dependentField, int fieldDependedOn)
      Sets the field on which a dependent field depends.
      void setLengthDependency(java.lang.String dependentField, java.lang.String fieldDependedOn)
      Sets the field on which a dependent field depends.
      void setName(java.lang.String name)
      Sets the name of this record format.
      void setOffsetDependency(int dependentField, int fieldDependedOn)
      Sets the field on which a dependent field depends.
      void setOffsetDependency(java.lang.String dependentField, java.lang.String fieldDependedOn)
      Sets the field on which a dependent field depends.
      void setRecordFormatID(java.lang.String id)
      Sets the record format ID.
      void setRecordFormatType(int type)
      Sets the record format type.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • FIXED_LAYOUT_LENGTH

        public static final int FIXED_LAYOUT_LENGTH
        This constant is only used for record level writing.
        See Also:
        Constant Field Values

      • VARIABLE_LAYOUT_LENGTH

        public static final int VARIABLE_LAYOUT_LENGTH
        This constant is only used for record level writing.
        See Also:
        Constant Field Values

    • Constructor Detail

      • RecordFormat

        public RecordFormat()
        Constructs a RecordFormat object.
        Note: When using this object with the record level access classes, the version of the constructor that takes name must be used.
        See Also:
        RecordFormat(java.lang.String)

      • RecordFormat

        public RecordFormat(java.lang.String name)
        Constructs a RecordFormat object. It uses the name specified.
        Note: Use this version of the constructor when the object is being used with the record level access classes.
        Parameters:
        name - The name of the record format. The name is converted to uppercase by this method. When using this object with the record level access classes, the name must be the name of the record format for the file that is being described.

    • Method Detail

      • addFieldDescription

        public void addFieldDescription(FieldDescription field)
        Adds a field description to this record format. The field description is added to the end of the field descriptions in this object.
        Parameters:
        field - The field description to be added.

      • addKeyFieldDescription

        public void addKeyFieldDescription(int index)
        Adds a key field description to this record format. The key field description is determined by the index of a field description that was already added to this object. The key field description is added to the end of the key field descriptions in this object. The order in which the key field descriptions are added must match the order of the key fields in the files for which this record format is meant.
        Parameters:
        index - The index of a field description that was already added to this object via addFieldDescription(). The index must be in the range zero to getNumberOfFields() - 1.

      • addKeyFieldDescription

        public void addKeyFieldDescription(java.lang.String name)
        Adds a key field description to this record format. The key field description is determined by the name of a field description that was already added to this object. The key field description is added to the end of the key field descriptions in this object. The order in which the key field descriptions are added must match the order of the key fields in the files for which this record format is meant.
        Parameters:
        name - The name of a field description that was already added to this object via addFieldDescription(). The name is case sensitive.

      • addPropertyChangeListener

        public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
        Adds a listener to be notified when the value of any bound property is changed. The propertyChange method will be called.
        Parameters:
        listener - The PropertyChangeListener.
        See Also:
        removePropertyChangeListener(java.beans.PropertyChangeListener)

      • addVetoableChangeListener

        public void addVetoableChangeListener(java.beans.VetoableChangeListener listener)
        Adds a listener to be notified when the value of any constrained property is changed. The vetoableChange method will be called.
        Parameters:
        listener - The VetoableChangeListener.
        See Also:
        removeVetoableChangeListener(java.beans.VetoableChangeListener)

      • getDelimiter

        public char getDelimiter()
        Returns the delimiter. The delimiter is the character used to separate variable length fields when the record is written using the line data record writer class. This value is only valid when the record format type is VARIABLE_LAYOUT_LENGTH.
        Returns:
        The delimiter.

      • getFieldDescription

        public FieldDescription getFieldDescription(int index)
        Returns the field description at the specified index.
        Parameters:
        index - The index of the field description. The index must be in the range zero to getNumberOfFields() - 1.
        Returns:
        The field description.

      • getFieldDescription

        public FieldDescription getFieldDescription(java.lang.String name)
        Returns the field description with the specified name.
        Parameters:
        name - The name of the field description. The name is case sensitive.
        Returns:
        The field description.

      • getFieldDescriptions

        public FieldDescription[] getFieldDescriptions()
        Returns the field descriptions that make up this object.
        Returns:
        The field descriptions. An array of size zero is returned if no fields have been added to this object.

      • getFieldNames

        public java.lang.String[] getFieldNames()
        Returns the names of the field descriptions that make up this record format.
        Returns:
        The names of the field descriptions. An array of size zero is returned if no fields have been added to this object.

      • getIndexOfFieldName

        public int getIndexOfFieldName(java.lang.String name)
        Returns the index of the field description named name.
        Parameters:
        name - The name of the field description. The name is case sensitive.
        Returns:
        The index of the field description.

      • getIndexOfKeyFieldName

        public int getIndexOfKeyFieldName(java.lang.String name)
        Returns the index of the field description of the key field named name.
        Parameters:
        name - The name of the key field description. The name is case sensitive.
        Returns:
        The index of the key field description. This is the index of the key field description in the key field descriptions for this object. It is not the index of the field description in the field descriptions for this object.

      • getKeyFieldDescription

        public FieldDescription getKeyFieldDescription(int index)
        Returns the field description of the key field at the specified index.
        Parameters:
        index - The index of the key field description in the key field descriptions for this object.
        Returns:
        The key field description.

      • getKeyFieldDescription

        public FieldDescription getKeyFieldDescription(java.lang.String name)
        Returns the field description of the key field with the specified name.
        Parameters:
        name - The name of the key field description. The name is case sensitive.
        Returns:
        The key field description.

      • getKeyFieldDescriptions

        public FieldDescription[] getKeyFieldDescriptions()
        Returns the key field descriptions that make up this object.
        Returns:
        The key field descriptions.

      • getKeyFieldNames

        public java.lang.String[] getKeyFieldNames()
        Returns the names of the field descriptions of the keys that make up this record format.
        Returns:
        The names of the key field descriptions. If no key field descriptions exist, an array of size 0 is returned.

      • getLengthDependency

        public int getLengthDependency(int index)
        Returns the index of the field description on which the field description at the specified index depends.
        Parameters:
        index - The index of the field description. The index must be in the range 0 to getNumberOfFields() - 1.
        Returns:
        The index of the field description on which the field description at the specified index depends. If index is not the index of a dependent field, -1 is returned.

      • getLengthDependency

        public int getLengthDependency(java.lang.String name)
        Returns the index of the field description on which the field description with the specified name depends.
        Parameters:
        name - The name of the field description. The name is case sensitive.
        Returns:
        The index of the field description on which the field description with the specified name depends. If name is not the name of a dependent field, -1 is returned.

      • getName

        public java.lang.String getName()
        Returns the name of this record format.
        Returns:
        The name of this record format. If the name has not been set, an empty string is returned.

      • getNewRecord

        public Record getNewRecord()
        Returns a new record based on this record format, which contains default values for the contents of the fields. The default values are determined as follows:
        1. Use the value specified for the DFT keyword on the field description object for a particular field.
        2. If no value was specified for the DFT keyword, use the default value from the AS400DataType object specified when constructing the field description object for a particular field.
        Returns:
        A record based on this record format. If no field descriptions have been added to this object, null is returned.

      • getNewRecord

        public Record getNewRecord(java.lang.String recordName)
        Returns a new record based on this record format, which contains default values for the contents of the fields. The default values are determined as follows:
        1. Use the value specified for the DFT keyword on the field description object for a particular field.
        2. If no value was specified for the DFT keyword, use the default value from the AS400DataType object specified when constructing the field description object for a particular field.
        Parameters:
        recordName - The name to assign to the Record object being returned.
        Returns:
        A record based on this record format. If no field descriptions have been added to this object, null is returned.

      • getNewRecord

        public Record getNewRecord(byte[] contents)
                    throws java.io.UnsupportedEncodingException
        Returns a new record based on this record format, which contains data from the specified byte array.
        Parameters:
        contents - The data with which to initialize the contents of the record. The length of contents must be greater than zero.
        Returns:
        A record based on this record format. If no field descriptions have been added to this object, null is returned.
        Throws:
        java.io.UnsupportedEncodingException - If an error occurs during conversion.

      • getNewRecord

        public Record getNewRecord(byte[] contents,
                  java.lang.String recordName)
                    throws java.io.UnsupportedEncodingException
        Returns a new record based on this record format, which contains data from the specified byte array.
        Parameters:
        contents - The data with which to initialize the contents of the record. The length of contents must be greater than zero.
        recordName - The name to assign to the Record object being returned.
        Returns:
        A record based on this record format. If no field descriptions have been added to this object, null is returned.
        Throws:
        java.io.UnsupportedEncodingException - If an error occurs during conversion.

      • getNewRecord

        public Record getNewRecord(byte[] contents,
                  int offset)
                    throws java.io.UnsupportedEncodingException
        Returns a new record based on this record format, which contains data from the specified byte array.
        Parameters:
        contents - The data with which to initialize the contents of the record. The length of contents must be greater than zero.
        offset - The offset in contents at which to start. The offset cannot be less than zero.
        Returns:
        A record based on this record format. If no field descriptions have been added to this object, null is returned.
        Throws:
        java.io.UnsupportedEncodingException - If an error occurs during conversion.

      • getNewRecord

        public Record getNewRecord(byte[] contents,
                  int offset,
                  java.lang.String recordName)
                    throws java.io.UnsupportedEncodingException
        Returns a new record based on this record format, which contains data from the specified byte array.
        Parameters:
        contents - The data with which to initialize the contents of the record. The length of contents must be greater than zero.
        offset - The offset in contents at which to start. The offset cannot be less than zero.
        recordName - The name to assign to the Record object being returned.
        Returns:
        A record based on this record format. If no field descriptions have been added to this object, null is returned.
        Throws:
        java.io.UnsupportedEncodingException - If an error occurs during conversion.

      • getNumberOfFields

        public int getNumberOfFields()
        Returns the number of field descriptions in this record format.
        Returns:
        The number of field descriptions in this record format.

      • getNumberOfKeyFields

        public int getNumberOfKeyFields()
        Returns the number of key field descriptions in this record format.
        Returns:
        The number of key field descriptions in this record format.

      • getOffsetDependency

        public int getOffsetDependency(int index)
        Returns the index of the field description on which the field description at the specified index depends.
        Parameters:
        index - The index of the field description. The index must be in the range 0 to getNumberOfFields() - 1.
        Returns:
        The index of the field description on which the field description at the specified index depends. If index is not the index of a dependent field, -1 is returned.

      • getOffsetDependency

        public int getOffsetDependency(java.lang.String name)
        Returns the index of the field description on which the field description with the specified name depends.
        Parameters:
        name - The name of the field description. The name is case sensitive.
        Returns:
        The index of the field description on which the field description with the specified name depends. If name is not the name of a dependent field, -1 is returned.

      • getRecordFormatID

        public java.lang.String getRecordFormatID()
        Returns the record format ID. The record format ID corresponds to a record format ID within a page definition defined on the system.
        Returns:
        The record format ID.

      • getRecordFormatType

        public int getRecordFormatType()
        Returns the record format type.
        Returns:
        The record format type.

      • removePropertyChangeListener

        public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
        Removes a listener from the change list. If the listener is not on the list, do nothing.
        Parameters:
        listener - The PropertyChangeListener.
        See Also:
        addPropertyChangeListener(java.beans.PropertyChangeListener)

      • removeVetoableChangeListener

        public void removeVetoableChangeListener(java.beans.VetoableChangeListener listener)
        Removes a listener from the veto change listeners list. If the listener is not on the list, do nothing.
        Parameters:
        listener - The VetoableChangeListener.
        See Also:
        addVetoableChangeListener(java.beans.VetoableChangeListener)

      • setDelimiter

        public void setDelimiter(char delimiter)
        Sets the delimiter. The delimiter is the character used to separate variable length fields when the record is written using the line data record writer class. This value is only valid when the record format type is VARIABLE_LAYOUT_LENGTH.
        Parameters:
        delimiter - The delimiter.

      • setLengthDependency

        public void setLengthDependency(int dependentField,
                       int fieldDependedOn)
        Sets the field on which a dependent field depends. Both fields must have been added already to this RecordFormat. The fieldDependedOn must have been added prior to adding the dependentField.
        Parameters:
        dependentField - The index of the dependent field. The dependentField must be in the range 1 to getNumberOfFields() - 1.
        fieldDependedOn - The index of a field on which this field depends. The fieldDependedOn must be in the range 0 to dependentField.

      • setLengthDependency

        public void setLengthDependency(java.lang.String dependentField,
                       java.lang.String fieldDependedOn)
        Sets the field on which a dependent field depends. Both fields must have been added already to this RecordFormat. The fieldDependedOn must have been added prior to adding the dependentField. The names of the fields are case sensitive.
        Parameters:
        dependentField - The name of the dependent field.
        fieldDependedOn - The name of a field on which this field depends. The index of fieldDependedOn in this RecordFormat must be less than the index of dependentField.

      • setName

        public void setName(java.lang.String name)
             throws java.beans.PropertyVetoException
        Sets the name of this record format.
        Parameters:
        name - The name of this record format. The name is converted to uppercase by this method.
        Throws:
        java.beans.PropertyVetoException - If a change is vetoed.

      • setOffsetDependency

        public void setOffsetDependency(int dependentField,
                       int fieldDependedOn)
        Sets the field on which a dependent field depends. Both fields must have been added already to this RecordFormat. The fieldDependedOn must have been added prior to adding the dependentField.
        Parameters:
        dependentField - The index of the dependent field. The dependentField must be in the range 1 to getNumberOfFields() - 1.
        fieldDependedOn - The index of a field on which this field depends. The fieldDependedOn must be in the range 0 to dependentField.

      • setOffsetDependency

        public void setOffsetDependency(java.lang.String dependentField,
                       java.lang.String fieldDependedOn)
        Sets the field on which a dependent field depends. Both fields must have been added already to this RecordFormat. The fieldDependedOn must have been added prior to adding the dependentField. The names of the fields are case sensitive.
        Parameters:
        dependentField - The name of the dependent field.
        fieldDependedOn - The name of a field on which this field depends. The index of fieldDependedOn in this RecordFormat must be less than the index of dependentField.

      • setRecordFormatID

        public void setRecordFormatID(java.lang.String id)
        Sets the record format ID. The length of the record format ID must be 10 characters or less. The record format ID corresponds to a record format ID within a page definition on the system. If the record format ID is less than 10 characters, it is padded to 10 characters in length with spaces.
        Parameters:
        id - The record format ID.

      • setRecordFormatType

        public void setRecordFormatType(int type)
        Sets the record format type. Valid values are FIXED_LAYOUT_LENGTH and VARIABLE_LAYOUT_LENGTH. This attribute is only valid when using the line record writer class.
        Parameters:
        type - The record format type.
JTOpen 10.7