Package com.ibm.mq.headers.pcf

Class PCFMessageAgent

java.lang.Object
com.ibm.mq.jmqi.JmqiObject
com.ibm.mq.headers.pcf.PCFAgent
com.ibm.mq.headers.pcf.PCFMessageAgent
public class PCFMessageAgent extends PCFAgent
General-purpose agent for sending PCF queries to a queue manager. Like the PCFAgent it extends, a PCFMessageAgent maintains a single queue manager connection and provides a simple method for sending PCF requests and returning the set of response messages. The PCFMessageAgent uses the PCFMessage class for requests and replies, which avoids exposure to the details of underlying PCF header structures. The PCFMessageAgent also provides the capability to check the header contents of a PCF response and throw a PCFException if the response indicates an error. The following example uses a PCFMessageAgent to obtain the list of local queues on the queue manager. 
     import com.ibm.mq.headers.pcf.*;

     ...

     try
     {
       PCFMessageAgent agent = new PCFMessageAgent ("localhost", 1414, "CLIENT");
       PCFMessage   request = new PCFMessage (CMQCFC.MQCMD_INQUIRE_Q_NAMES);

       request.addParameter (CMQC.MQCA_Q_NAME, "*");
       request.addParameter (CMQC.MQIA_Q_TYPE, MQC.MQQT_LOCAL);

       PCFMessage []   responses = agent.send (request);
       String []   names = (String []) responses [0].getParameterValue (CMQCFC.MQCACF_Q_NAMES);

       for (int i = 0; i < names.length; i++)
       {
         System.out.println ("Queue: " + names [i]);
       }
     }

     catch (PCFException pcfe)
     {
       System.err.println ("PCF error: " + pcfe);
     }

     catch (MQDataException mqe)
     {
       System.err.println (mqe);
     }

     catch (IOException ioe)
     {
       System.err.println (ioe);
     }

  • Constructor Details

    • PCFMessageAgent

      public PCFMessageAgent()
      Default constructor. Initializes a new PCFMessageAgent with no queue manager connection.

    • PCFMessageAgent

      public PCFMessageAgent(MQQueueManager qmanager) throws MQDataException
      Initializes a new PCFMessageAgent with an existing queue manager connection.
      Parameters:
      qmanager - an existing queue manager connection
      Throws:
      MQDataException - if the queue manager cannot be accessed

    • PCFMessageAgent

      public PCFMessageAgent(String host, int port, String channel) throws MQDataException
      Initializes a new PCFMessageAgent with a client connection to a queue manager.
      Parameters:
      host - the hostname or IP address where the queue manager resides
      port - the port on which the queue manager listens for incoming channel connections
      channel - the client channel to use for the connection
      Throws:
      MQDataException - if the connection cannot be established

    • PCFMessageAgent

      public PCFMessageAgent(String qmanager) throws MQDataException
      Initializes a new PCFMessageAgent with a bindings connection to a queue manager.
      Parameters:
      qmanager - the name of the queue manager
      Throws:
      MQDataException - if the connection cannot be established

  • Method Details

    • send

      public PCFMessage[] send(PCFMessage request) throws PCFException, MQDataException, IOException
      Sends a PCF request to the connected queue manager and returns the responses.
      Parameters:
      request - the PCF request message
      Returns:
      an array of PCF response messages. A single PCF request can generate multiple replies.
      Throws:
      PCFException - if the response indicates an error in PCF processing
      MQDataException - if there is a problem with the request or response
      IOException - if there is a problem with reading or writing
      See Also:

    • send

      public PCFMessage[] send(PCFMessage request, boolean check) throws PCFException, MQDataException, IOException
      Deprecated.
      Use setCheckResponses and send(com.ibm.mq.headers.pcf.PCFMessage)
      Sends a PCF request to the connected queue manager and returns the responses.
      Parameters:
      request - the PCF request message
      check - if set, the agent will check the reason code in the MQCFH of the responses and generate a PCFException if MQRCCF_COMMAND_FAILED appears
      Returns:
      an array of PCF response messages. A single PCF request can generate multiple replies.
      Throws:
      PCFException - if the responses include MQRCCF_COMMAND_FAILED
      MQDataException - if there is a problem with the request or response
      IOException - if there is a problem with reading or writing
      See Also:

    • send

      public PCFMessage[] send(PCFMessage request, boolean check, boolean usePlatformSettings) throws PCFException, MQDataException, IOException
      Deprecated.
      Use setCheckResponses/setUsePlatformSettings and send(com.ibm.mq.headers.pcf.PCFMessage)
      Sends a PCF request to the connected queue manager and returns the responses.
      Parameters:
      request - the PCF request message
      check - if set, the agent will check the reason code in the MQCFH of the responses and generate a PCFException if MQRCCF_COMMAND_FAILED appears
      usePlatformSettings - use the platform settings of the connected queue manager. For example, if the connected queue manager is a z/OS queue manager and the request MQCFH contains type MQCFT_COMMAND; the agent will change the type to type MQCFT_COMMAND_XR
      Returns:
      an array of PCF response messages. A single PCF request can generate multiple replies.
      Throws:
      PCFException - if the responses include MQRCCF_COMMAND_FAILED
      MQDataException - if there is a problem with the request or response
      IOException - if there is a problem with reading or writing
      See Also:

    • setCheckResponses

      public void setCheckResponses(boolean option)
      If this option is set, the send method throws a PCFException if the responses include a PCF message with the reason code MQRCCF_COMMAND_FAILED in the MQCFH header. By default, this option is set.
      Parameters:
      option - true - check for command failure in message response.

    • setUsePlatformSettings

      public void setUsePlatformSettings(boolean option)
      If this option is set, the send method alters the MQCFH contained within the PCFMessage request if necessary to match the platform of the connected queue manager. This occurs, for example, if the connected queue manager is a z/OS queue manager and the request MQCFH contains type MQCFT_COMMAND; the agent will change the type to type MQCFT_COMMAND_XR. By default, this option is set.
      Parameters:
      option - true - match the platform of the connected queue manager.