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)
                        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.
    
    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,
                      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.

Methods inherited from class java.lang.Object

NO_FORMATTING

RETURN_FORMATTING_CHARACTERS

SUBSTITUTE_FORMATTING_CHARACTERS

CCSID_OF_JOB

NEXT

FIRST

MessageFile

MessageFile

MessageFile

addPropertyChangeListener

addVetoableChangeListener

substituteFormattingCharacters

getHelpTextFormatting

getPath

getMessage

getMessage

getMessage

getMessage

getMessage

getMessage

getMessage

getSystem

removePropertyChangeListener

removeVetoableChangeListener

setHelpTextFormatting

setPath

setSystem