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

The MessageFile class allows a user to get a message from an AS/400 message file. It returns 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 AS/400 formatting characters. The formatting characters are:
  3. Substitute formatting characters - the MessageFile class replaces AS/400 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.

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());
 

See Also:
AS400Message, CommandCall, ProgramCall, QSYSObjectPathName, Serialized Form

Field Summary
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
MessageFile()
          Constructs a MessageFile object.
MessageFile(AS400 system)
          Constructs a MessageFile object.
MessageFile(AS400 system, java.lang.String path)
          Constructs a message file object.
 
Method Summary
 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, 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 pathname for the message file.
 AS400 getSystem()
          Returns the AS/400 which contains the message file.
 void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
          Removes this PropertyChangeListener from the internal list.
 void removeVetoableChangeListener(java.beans.VetoableChangeListener listener)
          Removes this VetoableChangeListener from the internal list.
 void setHelpTextFormatting(int value)
          Sets the help text formatting value.
 void setPath(java.lang.String path)
          Sets the message file name.
 void setSystem(AS400 system)
          Sets the AS/400 which contains the message file.
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.

RETURN_FORMATTING_CHARACTERS

public static final int RETURN_FORMATTING_CHARACTERS
Constant indicating formatting characters are left in the help text.

SUBSTITUTE_FORMATTING_CHARACTERS

public static final int SUBSTITUTE_FORMATTING_CHARACTERS
Constant indicating MessageFile should replace formatting characters with newline and space characters.
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 AS/400. The message file name must be provided later.
Parameters:
system - The AS/400 which contains the message file.

MessageFile

public MessageFile(AS400 system,
                   java.lang.String path)
Constructs a message file object. It uses the specified AS/400 and message file name.
Parameters:
system - The AS/400 which contains the message file
path - The integrated file system pathname 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/MSGFILE.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. The PropertyChangeListener object is added to a list of PropertyChangeListeners managed by this MessageFile. It can be removed with removePropertyChangeListener.
Parameters:
listener - The PropertyChangeListener.
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 about to be changed. The VetoableChangeListener object is added to a list of listeners managed by this MessageFile, it can be removed with removeVetoableChangeListener.
Parameters:
listener - The VetoableChangeListener.
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:
Parameters:
sourceText - The source text.
Returns:
The formatted text.

getHelpTextFormatting

public int getHelpTextFormatting()
Returns the status of help text formatting. Possible values are:
Returns:
The status of help text formatting.

getPath

public java.lang.String getPath()
Returns the integrated file system pathname for the message file. It will return null if not previously set.
Returns:
The integrated file system pathname for the program.

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.
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 AS/400.
java.beans.PropertyVetoException - If a change is vetoed.
ObjectDoesNotExistException - If the AS/400 object does not exist.

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.
type - The bidi message string type, as defined by the CDRA (Character Data Representataion 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 AS/400.
java.beans.PropertyVetoException - If a change is vetoed.
ObjectDoesNotExistException - If the AS/400 object does not exist.

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 AS/400 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.
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 AS/400.
java.beans.PropertyVetoException - If a change is vetoed.
ObjectDoesNotExistException - If the AS/400 object does not exist.

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 AS/400 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.
substitutionText - The substitution text.
type - The bidi message string type, as defined by the CDRA (Character Data Representataion 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 AS/400.
java.beans.PropertyVetoException - If a change is vetoed.
ObjectDoesNotExistException - If the AS/400 object does not exist.

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 AS/400.
Parameters:
ID - The message identifier.
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 AS/400.
java.beans.PropertyVetoException - If a change is vetoed.
ObjectDoesNotExistException - If the AS/400 object does not exist.

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 AS/400.
Parameters:
ID - The message identifier.
substitutionText - The substitution text.
type - The bidi message string type, as defined by the CDRA (Character Data Representataion 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 AS/400.
java.beans.PropertyVetoException - If a change is vetoed.
ObjectDoesNotExistException - If the AS/400 object does not exist.

getSystem

public AS400 getSystem()
Returns the AS/400 which contains the message file.
Returns:
The AS/400 which contains the message file.

removePropertyChangeListener

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

removeVetoableChangeListener

public void removeVetoableChangeListener(java.beans.VetoableChangeListener listener)
Removes this VetoableChangeListener from the internal list. If the VetoableChangeListener is not on the list, nothing is done.
Parameters:
listener - The VetoableChangeListener.
See Also:
addVetoableChangeListener(java.beans.VetoableChangeListener)

setHelpTextFormatting

public void setHelpTextFormatting(int value)
                           throws java.beans.PropertyVetoException
Sets the help text formatting value. Possible values are:
Parameters:
value - The help text formatting value.
Throws:
java.beans.PropertyVetoException - If a change is vetoed.

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 AS/400.
Parameters:
path - The integrated file system pathname for the message file. That is, the message file name as a fully qualified path name in the library file system. The library and 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 a change is vetoed.

setSystem

public void setSystem(AS400 system)
               throws ExtendedIllegalStateException,
                      java.beans.PropertyVetoException
Sets the AS/400 which contains the message file. The system cannot be changed after retrieving a message from the AS/400.
Parameters:
system - The AS/400 which contains the message file.
Throws:
java.beans.PropertyVetoException - If a change is vetoed.