com.ibm.as400.access

Class MessageFile

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


    public class MessageFile
    extends java.lang.Object
    implements java.io.Serializable
    Represents a message file object on the system. This class allows a user to get a message from a message file, returning an AS400Message object which contains the message. The calling program can optionally supply substitution text for the message.

    MessageFile will optionally format the message's associated help text. Three options are available for help text formatting:

    1. No formatting - the help text is returned as a string of characters. This is the default.
    2. Include formatting characters - the help text contains formatting characters. The formatting characters are:
      • &N -- Force a new line.
      • &P -- Force a new line and indent the new line six characters.
      • &B -- Force a new line and indent the new line four characters.
    3. Substitute formatting characters - the MessageFile class replaces system formatting characters with newline and space characters.
    The difference between options 2 and 3 are with line wrapping. If the formatting characters remain the application can handle line wrapping and indentation. If the MessageFile class inserts newline and space characters, Java components will handle line wrapping.

    Note: To return formatting characters, you must call setHelpTextFormatting prior to calling any of the getMessage() methods.

    For example, to retrieve and print a message:

     AS400 system = new AS400("mysystem.mycompany.com");
     MessageFile messageFile = new MessageFile(system);
     messageFile.setPath("/QSYS.LIB/QCPFMSG.MSGF");
     AS400Message message = messageFile.getMessage("CPD0170");
     System.out.println(message.getText());
     

    You can also sequentially retrieve messages from a message file by using the FIRST and NEXT message id values.

     AS400Message msg = messageFile.getMessage(MessageFile.FIRST);
    
     while (msg != null) {
        System.out.println(msg.getID() + " = " + msg.getText());
        msg = messageFile.getMessage(MessageFile.NEXT);
     }
    
    See Also:
    AS400Message, CommandCall, ProgramCall, QSYSObjectPathName, Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field and Description
      static int CCSID_OF_JOB
      Constant indicating "the CCSID of the job".
      static java.lang.String FIRST
      Constant indicating we are going to retrieve the first message in the message file.
      static java.lang.String NEXT
      Constant indicating we are going to retrieve the next message (using the previous message as a starting point).
      static int NO_FORMATTING
      Constant indicating help text should not be formatted.
      static int RETURN_FORMATTING_CHARACTERS
      Constant indicating formatting characters are left in the help text.
      static int SUBSTITUTE_FORMATTING_CHARACTERS
      Constant indicating MessageFile should replace formatting characters with newline and space characters.
    • Constructor Summary

      Constructors 
      Constructor and Description
      MessageFile()
      Constructs a MessageFile object.
      MessageFile(AS400 system)
      Constructs a MessageFile object.
      MessageFile(AS400 system, java.lang.String path)
      Constructs a MessageFile object.
    • Method Summary

      Methods 
      Modifier and Type Method and Description
      void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
      Adds a PropertyChangeListener.
      void addVetoableChangeListener(java.beans.VetoableChangeListener listener)
      Adds a VetoableChangeListener.
      int getHelpTextFormatting()
      Returns the status of help text formatting.
      AS400Message getMessage(java.lang.String ID)
      Returns an AS400Message object containing the object.
      AS400Message getMessage(java.lang.String ID, byte[] substitutionText)
      Returns an AS400Message object containing the message.
      AS400Message getMessage(java.lang.String ID, byte[] substitutionText, int type)
      Returns an AS400Message object containing the message.
      AS400Message getMessage(java.lang.String ID, byte[] substitutionText, int type, int ccsidOfSubstitutionText, int ccsidToConvertTo)
      Returns an AS400Message object containing the message.
      AS400Message getMessage(java.lang.String ID, int type)
      Returns an AS400Message object containing the object.
      AS400Message getMessage(java.lang.String ID, java.lang.String substitutionText)
      Returns an AS400Message object containing the message.
      AS400Message getMessage(java.lang.String ID, java.lang.String substitutionText, int type)
      Returns an AS400Message object containing the message.
      java.lang.String getPath()
      Returns the integrated file system path name of the message file.
      AS400 getSystem()
      Returns the system object representing the system on which the message file exists.
      void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
      Removes the PropertyChangeListener.
      void removeVetoableChangeListener(java.beans.VetoableChangeListener listener)
      Removes the VetoableChangeListener.
      void setHelpTextFormatting(int helpTextFormatting)
      Sets the help text formatting value.
      void setPath(java.lang.String path)
      Sets the message file name.
      void setSystem(AS400 system)
      Sets the system object representing the system on which the message file exists.
      static java.lang.String substituteFormattingCharacters(java.lang.String sourceText)
      Substitutes formatting characters with appropriate new line and indent characters.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • NO_FORMATTING

        public static final int NO_FORMATTING
        Constant indicating help text should not be formatted.
        See Also:
        Constant Field Values
      • RETURN_FORMATTING_CHARACTERS

        public static final int RETURN_FORMATTING_CHARACTERS
        Constant indicating formatting characters are left in the help text.
        See Also:
        Constant Field Values
      • SUBSTITUTE_FORMATTING_CHARACTERS

        public static final int SUBSTITUTE_FORMATTING_CHARACTERS
        Constant indicating MessageFile should replace formatting characters with newline and space characters.
        See Also:
        Constant Field Values
      • CCSID_OF_JOB

        public static final int CCSID_OF_JOB
        Constant indicating "the CCSID of the job".
        See Also:
        Constant Field Values
      • NEXT

        public static final java.lang.String NEXT
        Constant indicating we are going to retrieve the next message (using the previous message as a starting point).
        See Also:
        Constant Field Values
      • FIRST

        public static final java.lang.String FIRST
        Constant indicating we are going to retrieve the first message in the message file.
        See Also:
        Constant Field Values
    • Constructor Detail

      • MessageFile

        public MessageFile()
        Constructs a MessageFile object. The system and message file name must be provided later.
      • MessageFile

        public MessageFile(AS400 system)
        Constructs a MessageFile object. It uses the specified system. The message file name must be provided later.
        Parameters:
        system - The system object representing the system on which the message file exists.
      • MessageFile

        public MessageFile(AS400 system,
                   java.lang.String path)
        Constructs a MessageFile object. It uses the specified system and message file name.
        Parameters:
        system - The system object representing the system on which the message file exists.
        path - The integrated file system path name for the message file. That is, the message file name as a fully qualified path name in the library file system. The library and message file name must each be 10 characters or less. The extension for message files is .msgf. For example, /QSYS.LIB/MYLIB.LIB/MYFILE.MSGF.
    >
    • Method Detail

      • addPropertyChangeListener

        public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
        Adds a PropertyChangeListener. The specified PropertyChangeListener's propertyChange() method will be called each time the value of any bound property is changed.
        Parameters:
        listener - The listener.
        See Also:
        removePropertyChangeListener(java.beans.PropertyChangeListener)
      • addVetoableChangeListener

        public void addVetoableChangeListener(java.beans.VetoableChangeListener listener)
        Adds a VetoableChangeListener. The specified VetoableChangeListener's vetoableChange() method will be called each time the value of any constrained property is changed.
        Parameters:
        listener - The listener.
        See Also:
        removeVetoableChangeListener(java.beans.VetoableChangeListener)
      • substituteFormattingCharacters

        public static java.lang.String substituteFormattingCharacters(java.lang.String sourceText)
        Substitutes formatting characters with appropriate new line and indent characters. The formatting characters are:
        • &N -- Force a new line.
        • &P -- Force a new line and indent the new line six characters.
        • &B -- Force a new line and indent the new line four characters.
        Parameters:
        sourceText - The source text.
        Returns:
        The formatted text.
      • getHelpTextFormatting

        public int getHelpTextFormatting()
        Returns the status of help text formatting. Possible values are:
        • NO_FORMATTING - The help text is returned as a string of characters. This is the default.
        • RETURN_FORMATTING_CHARACTERS - The help text contains formatting characters. The formatting characters are:
          • &N -- Force a new line.
          • &P -- Force a new line and indent the new line six characters.
          • &B -- Force a new line and indent the new line four characters.
        • SUBSTITUTE_FORMATTING_CHARACTERS - The MessageFile class replaces formatting characters with newline and space characters.
        Returns:
        The status of help text formatting.
      • getPath

        public java.lang.String getPath()
        Returns the integrated file system path name of the message file.
        Returns:
        The fully-qualified message file name, or an empty string ("") if not set.
      • getMessage

        public AS400Message getMessage(java.lang.String ID,
                              int type)
                                throws AS400SecurityException,
                                       ErrorCompletingRequestException,
                                       java.lang.InterruptedException,
                                       java.io.IOException,
                                       ObjectDoesNotExistException,
                                       java.beans.PropertyVetoException
        Returns an AS400Message object containing the object. The system and message file name must be set before calling this method.
        Parameters:
        ID - The message identifier, FIRST, or NEXT.
        type - The bidi message string type, as defined by the CDRA (Character Data Representation Architecture). See BidiStringType for more information and valid values.
        Returns:
        An AS400Message object containing the message.
        Throws:
        AS400SecurityException - If a security or authority error occurs.
        ErrorCompletingRequestException - If an error occurs before the request is completed.
        java.lang.InterruptedException - If this thread is interrupted.
        java.io.IOException - If an error occurs while communicating with the system.
        ObjectDoesNotExistException - If the object does not exist on the system.
        java.beans.PropertyVetoException - If any of the registered listeners vetos the property change.
        See Also:
        setHelpTextFormatting(int)
      • getMessage

        public AS400Message getMessage(java.lang.String ID,
                              java.lang.String substitutionText)
                                throws AS400SecurityException,
                                       ErrorCompletingRequestException,
                                       java.lang.InterruptedException,
                                       java.io.IOException,
                                       ObjectDoesNotExistException,
                                       java.beans.PropertyVetoException
        Returns an AS400Message object containing the message. The system and message file name must be set before calling this method. Up to 1024 bytes of substitution text can be supplied to this method. The calling program is responsible for correctly formatting the string containing the substitution text for the specified message.

        For example, using CL command DSPMSGD, we see the format of the substitution text for message CPD0170 is char 4, char 10, char 10. Passing string

        "12  abcd      xyz"
        as the substitution text on this call means "12" will be substituted for &1, "abcd" will be substituted for &2, and "xyz" will be substituted for &3.
        Parameters:
        ID - The message identifier, FIRST, or NEXT.
        substitutionText - The substitution text.
        Returns:
        An AS400Message object containing the message.
        Throws:
        AS400SecurityException - If a security or authority error occurs.
        ErrorCompletingRequestException - If an error occurs before the request is completed.
        java.lang.InterruptedException - If this thread is interrupted.
        java.io.IOException - If an error occurs while communicating with the system.
        ObjectDoesNotExistException - If the object does not exist on the system.
        java.beans.PropertyVetoException - If any of the registered listeners vetos the property change.
        See Also:
        setHelpTextFormatting(int)
      • getMessage

        public AS400Message getMessage(java.lang.String ID,
                              java.lang.String substitutionText,
                              int type)
                                throws AS400SecurityException,
                                       ErrorCompletingRequestException,
                                       java.lang.InterruptedException,
                                       java.io.IOException,
                                       ObjectDoesNotExistException,
                                       java.beans.PropertyVetoException
        Returns an AS400Message object containing the message. The system and message file name must be set before calling this method. Up to 1024 bytes of substitution text can be supplied to this method. The calling program is responsible for correctly formatting the string containing the substitution text for the specified message.

        For example, using CL command DSPMSGD, we see the format of the substitution text for message CPD0170 is char 4, char 10, char 10. Passing string

        "12  abcd      xyz"
        as the substitution text on this call means "12" will be substituted for &1, "abcd" will be substituted for &2, and "xyz" will be substituted for &3.
        Parameters:
        ID - The message identifier, FIRST, or NEXT.
        substitutionText - The substitution text.
        type - The bidi message string type, as defined by the CDRA (Character Data Representation Architecture). See BidiStringType for more information and valid values.
        Returns:
        An AS400Message object containing the message.
        Throws:
        AS400SecurityException - If a security or authority error occurs.
        ErrorCompletingRequestException - If an error occurs before the request is completed.
        java.lang.InterruptedException - If this thread is interrupted.
        java.io.IOException - If an error occurs while communicating with the system.
        ObjectDoesNotExistException - If the object does not exist on the system.
        java.beans.PropertyVetoException - If any of the registered listeners vetos the property change.
        See Also:
        setHelpTextFormatting(int)
      • getMessage

        public AS400Message getMessage(java.lang.String ID,
                              byte[] substitutionText)
                                throws AS400SecurityException,
                                       ErrorCompletingRequestException,
                                       java.lang.InterruptedException,
                                       java.io.IOException,
                                       ObjectDoesNotExistException,
                                       java.beans.PropertyVetoException
        Returns an AS400Message object containing the message. The system and message file name must be set before calling this method. Up to 1024 bytes of substitution text can be supplied to this method. The byte array is not changed or converted before being sent to the system.
        Parameters:
        ID - The message identifier, FIRST, or NEXT.
        substitutionText - The substitution text. The bytes are assumed to be in the CCSID of the job.
        Returns:
        An AS400Message object containing the message.
        Throws:
        AS400SecurityException - If a security or authority error occurs.
        ErrorCompletingRequestException - If an error occurs before the request is completed.
        java.lang.InterruptedException - If this thread is interrupted.
        java.io.IOException - If an error occurs while communicating with the system.
        ObjectDoesNotExistException - If the object does not exist on the system.
        java.beans.PropertyVetoException - If any of the registered listeners vetos the property change.
        See Also:
        setHelpTextFormatting(int)
      • getMessage

        public AS400Message getMessage(java.lang.String ID,
                              byte[] substitutionText,
                              int type)
                                throws AS400SecurityException,
                                       ErrorCompletingRequestException,
                                       java.lang.InterruptedException,
                                       java.io.IOException,
                                       ObjectDoesNotExistException,
                                       java.beans.PropertyVetoException
        Returns an AS400Message object containing the message. The system and message file name must be set before calling this method. Up to 1024 bytes of substitution text can be supplied to this method. The byte array is not changed or converted before being sent to the system.
        Parameters:
        ID - The message identifier, FIRST, or NEXT.
        substitutionText - The substitution text. The bytes are assumed to be in the CCSID of the job.
        type - The bidi message string type, as defined by the CDRA (Character Data Representation Architecture). See BidiStringType for more information and valid values.
        Returns:
        An AS400Message object containing the message.
        Throws:
        AS400SecurityException - If a security or authority error occurs.
        ErrorCompletingRequestException - If an error occurs before the request is completed.
        java.lang.InterruptedException - If this thread is interrupted.
        java.io.IOException - If an error occurs while communicating with the system.
        ObjectDoesNotExistException - If the object does not exist on the system.
        java.beans.PropertyVetoException - If any of the registered listeners vetos the property change.
        See Also:
        setHelpTextFormatting(int)
      • getMessage

        public AS400Message getMessage(java.lang.String ID,
                              byte[] substitutionText,
                              int type,
                              int ccsidOfSubstitutionText,
                              int ccsidToConvertTo)
                                throws AS400SecurityException,
                                       ErrorCompletingRequestException,
                                       java.lang.InterruptedException,
                                       java.io.IOException,
                                       ObjectDoesNotExistException,
                                       java.beans.PropertyVetoException
        Returns an AS400Message object containing the message. The system and message file name must be set before calling this method. Up to 1024 bytes of substitution text can be supplied to this method. The byte array is not changed or converted before being sent to the system.
        Parameters:
        ID - The message identifier, FIRST, or NEXT.
        substitutionText - The substitution text.
        type - The bidi message string type, as defined by the CDRA (Character Data Representation Architecture). See BidiStringType for more information and valid values.
        ccsidOfSubstitutionText - The CCSID of the substitution text. The default value is CCSID_OF_JOB.
        ccsidToConvertTo - The CCSID in which the system should return the message text. The Toolbox then converts from that CCSID to Unicode when constructing the AS400Message. The default value is CCSID_OF_JOB.
        Returns:
        An AS400Message object containing the message.
        Throws:
        AS400SecurityException - If a security or authority error occurs.
        ErrorCompletingRequestException - If an error occurs before the request is completed.
        java.lang.InterruptedException - If this thread is interrupted.
        java.io.IOException - If an error occurs while communicating with the system.
        ObjectDoesNotExistException - If the object does not exist on the system.
        java.beans.PropertyVetoException - If any of the registered listeners vetos the property change.
        See Also:
        setHelpTextFormatting(int)
      • getSystem

        public AS400 getSystem()
        Returns the system object representing the system on which the message file exists.
        Returns:
        The system object representing the system on which the message file exists. If the system has not been set, null is returned.
      • removePropertyChangeListener

        public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
        Removes the PropertyChangeListener. If the PropertyChangeListener is not on the list, nothing is done.
        Parameters:
        listener - The listener object.
      • removeVetoableChangeListener

        public void removeVetoableChangeListener(java.beans.VetoableChangeListener listener)
        Removes the VetoableChangeListener. If the VetoableChangeListener is not on the list, nothing is done.
        Parameters:
        listener - The listener object.
      • setHelpTextFormatting

        public void setHelpTextFormatting(int helpTextFormatting)
                                   throws java.beans.PropertyVetoException
        Sets the help text formatting value.

        Note: To return formatting characters, call this method prior to calling any of the getMessage() methods.

        Parameters:
        helpTextFormatting - The help text formatting value. Possible values are:
        • NO_FORMATTING - The help text is returned as a string of characters. This is the default.
        • RETURN_FORMATTING_CHARACTERS - The help text contains formatting characters. The formatting characters are:
          • &N -- Force a new line.
          • &P -- Force a new line and indent the new line six characters.
          • &B -- Force a new line and indent the new line four characters.
        • SUBSTITUTE_FORMATTING_CHARACTERS - The MessageFile class replaces formatting characters with new line and space characters.
        Throws:
        java.beans.PropertyVetoException - If any of the registered listeners vetos the property change.
      • setPath

        public void setPath(java.lang.String path)
                     throws java.beans.PropertyVetoException
        Sets the message file name. The name cannot be changed after retrieving a message from the system.
        Parameters:
        path - The integrated file system path name for the message file. That is, the message file name as a fully qualified path name in the library file system. The library and message file name must each be 10 characters or less. The extension for message files is .msgf. For example, /QSYS.LIB/MYLIB.LIB/MYFILE.MSGF.
        Throws:
        java.beans.PropertyVetoException - If any of the registered listeners vetos the property change.
      • setSystem

        public void setSystem(AS400 system)
                       throws java.beans.PropertyVetoException
        Sets the system object representing the system on which the message file exists. The system cannot be changed after retrieving a message from the system.
        Parameters:
        system - The system object representing the system on which the message file exists.
        Throws:
        java.beans.PropertyVetoException - If any of the registered listeners vetos the property change.