IBM Support

IT12701: jmsadmin generates 'JMSADM4125 q unmappable replacement' error when altering queue definition

Subscribe

You can track all active APARs for this component.

 

APAR status

  • Closed as program error.

Error description

  • When using the JMSAdmin tool in IBM MQ v8.0 to alter the JMS
    administrative object for a queue, there is an unexpected error
    message and the object is not updated:
    
    InitCtx> alter q(Q1) CCSID(819)
    Unable to create a valid object, please check the parameters
    supplied
    JMSADM4125 Q UNMAPPABLEREPLACEMENT
    

Local fix

Problem summary

  • ****************************************************************
    USERS AFFECTED:
    This issue affects users of the IBM MQ V8 or V9 JMSAdmin tool
    who attempt to either:
    
      - define a JMS Queue or JMS Topic administered object and
    specify the UNMAPPABLEACTION (short name: UMA) and / or
    UNMAPPABLEREPLACEMENT (short name: UMR) properties.
    
      - alter an existing JMS Queue or JMS Topic object, even when
    the UMA/UMR attributes are not used.
    
    
    Platforms affected:
    MultiPlatform
    
    ****************************************************************
    PROBLEM DESCRIPTION:
    When using the IBM MQ V8.0/V9.0 JMSAdmin tool to either create
    or alter a JMS administered object that is either a JMS Queue or
    JMS Topic, properties associated with that object are validated
    internally by the JMSAdmin tool.
    
    The UNMAPPABLEACTION (short name: UMA) and UNMAPPABLEREPLACEMENT
    (short name: UMR) properties were not recognised as valid JMS
    Destination properties and, as such, this validation processing
    failed.
    
    For example, attempting to define a JMS Queue administered
    object using the following command:
    
      define Q(QUEUE1) QUEUE(QUEUE1) UMA(REPLACE) UMR(35)
    
    would result in the following error and the object would not be
    created in JNDI:
    
      Unable to create a valid object, please check the parameters
    supplied
      JMSADM4125 Q UMR
    
    Similarly, when attempting to alter an existing JMS Queue to JMS
    Topic administered object, even when not specifying the UMA/UMR
    properties, the error message shown in this APAR's Problem
    Description section would be returned to the user.
    

Problem conclusion

  • The JMSAdmin tool in IBM MQ V8.0 and V9.0 has been updated such
    that the new UNMAPPABLEACTION (short name: UMA) and
    UNMAPPABLEREPLACEMENT (short name: UMR) properties are
    recognised as valid properties to configure on a JMS Queue or
    JMS Topic JNDI administered object.
    
    In addition to the JMSAdmin tool changes under this APAR, the
    default Unmappable Character Action and Unmappable Character
    Replacement settings on a com.ibm.mq.MQMessage object, given by
    the class variables:
    
      - unmappableAction
    
    and
    
      - unMappableReplacement
    
    on the parent com.ibm.mq.MQMD class, are now set based off the
    system defaults in the Java MQI at the time the MQMD object is
    created.  These system defaults can be configured using the
    following two Java system properties:
    
      - com.ibm.mq.cfg.jmqi.UnmappableCharacterAction
      - com.ibm.mq.cfg.jmqi.UnmappableCharacterReplacement
    
    as documented in the Knowledge Center:
    
    http://www.ibm.com/support/knowledgecenter/SSFKSJ_9.0.0/com.ibm.
    mq.dev.doc/q120590_.htm
    
    Similarly, the default values on JMS Destination (Queue and
    Topic) objects are also set based off the system defaults in the
    Java MQI at the time at which these JMS Destination objects are
    defined.
    
    Prior to this APAR, the default unmappable character action
    configured on com.ibm.mq.MQMD and JMS Destination objects was:
    
        CodingErrorAction.REPORT
    
    which results in a java.nio.charset.CharacterCodingException
    being thrown back to the application when an encoding problem is
    encountered.
    
    The default unmappable character replacement on these objects
    was the UTF-8 representation of the question mark character,
    '?'.  This meant that the system defaults in the Java MQI
    (configured via the Java system properties noted above) would
    never be used.
    
    Note that the default system unmappable character action remains
    CodingErrorAction.REPORT and the default system unmappable
    character replacement byte remains the UTF-8 representation of
    the question mark character, '?'.
    
    ---------------------------------------------------------------
    The fix is targeted for delivery in the following PTFs:
    
    Version    Maintenance Level
    v8.0       8.0.0.6
    v9.0 CD    9.0.1
    v9.0 LTS   9.0.0.1
    
    The latest available maintenance can be obtained from
    'WebSphere MQ Recommended Fixes'
    http://www-1.ibm.com/support/docview.wss?rs=171&uid=swg27006037
    
    If the maintenance level is not yet available information on
    its planned availability can be found in 'WebSphere MQ
    Planned Maintenance Release Dates'
    http://www-1.ibm.com/support/docview.wss?rs=171&uid=swg27006309
    ---------------------------------------------------------------
    

Temporary fix

Comments

APAR Information

  • APAR number

    IT12701

  • Reported component name

    WMQ BASE MULTIP

  • Reported component ID

    5724H7251

  • Reported release

    800

  • Status

    CLOSED PER

  • PE

    NoPE

  • HIPER

    NoHIPER

  • Special Attention

    NoSpecatt / Xsystem

  • Submitted date

    2015-12-09

  • Closed date

    2016-07-11

  • Last modified date

    2017-06-01

  • APAR is sysrouted FROM one or more of the following:

  • APAR is sysrouted TO one or more of the following:

Fix information

  • Fixed component name

    WMQ BASE MULTIP

  • Fixed component ID

    5724H7251

Applicable component levels

  • R800 PSY

       UP

[{"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SSYHRD","label":"IBM MQ"},"Component":"","ARM Category":[],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"8.0.0.0","Edition":"","Line of Business":{"code":"LOB36","label":"IBM Automation"}}]

Document Information

Modified date:
01 June 2017