com.ibm.as400.access

Class MessageFile

  • All Implemented Interfaces:
    Serializable


    public class MessageFile
    extends Object
    implements 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 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 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 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,
                   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

      • substituteFormattingCharacters

        public static String substituteFormattingCharacters(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 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.
      • 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(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(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 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:
        PropertyVetoException - If any of the registered listeners vetos the property change.
      • setPath

        public void setPath(String path)
                     throws 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:
        PropertyVetoException - If any of the registered listeners vetos the property change.
      • setSystem

        public void setSystem(AS400 system)
                       throws 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:
        PropertyVetoException - If any of the registered listeners vetos the property change.