com.ibm.mq.jmqi.JmqiObject

com.ibm.mq.headers.pcf.PCFAgent

Direct Known Subclasses:: PCFMessageAgent

public class PCFAgent extends com.ibm.mq.jmqi.JmqiObject

General-purpose agent for sending PCF queries to a queue manager. A PCFAgent maintains a single queue manager connection and provides a simple method for sending PCF requests and returning the set of response messages. The following example uses a PCFAgent to obtain the list of local queues on the queue manager.

 PCFAgent agent = new PCFAgent("localhost", 1414, "CLIENT");
 MQMessage[] responses;
 PCFParameter[] parameters = {new MQCFST(CMQC.MQCA_Q_NAME, "*"),
                              new MQCFIN(CMQC.MQIA_Q_TYPE, MQC.MQQT_LOCAL)};
 MQCFH cfh;
 MQCFSL cfsl;
 
 responses = agent.send(CMQCFC.MQCMD_INQUIRE_Q_NAMES, parameters);
 
 cfh = new MQCFH(responses[0]);
 
 if (cfh.reason == 0) {
   cfsl = new MQCFSL(responses[0]);
 
   for (int i = 0; i < cfsl.strings.length; i++) {
     System.out.println("Queue: " + cfsl.strings[i]);
   }
 }
 else {
   throw new MQDataException(cfh.compCode, cfh.reason, agent);
 }

See Also:

Field Summary

Fields

Modifier and Type

Field

Description

static final int

MAXIMUM_ALLOWED_PREFIX_LENGTH

String

replyQueueName

Deprecated.
Use getReplyQueueName instead.

Fields inherited from class com.ibm.mq.jmqi.JmqiObject
COMP_JM, COMP_JN, COMP_JO
Constructor Summary

Constructors

Constructor

Description

PCFAgent()

Default constructor.

PCFAgent(MQQueueManager qmanager)

Initializes a new PCFAgent with an existing queue manager connection.

PCFAgent(String qmanager)

Initializes a new PCFAgent with a bindings connection to a queue manager.

PCFAgent(String host, int port, String channel)

Initializes a new PCFAgent with a client connection to a queue manager.
Method Summary

Modifier and Type

Method

Description

void

connect(MQQueueManager qmanagerP)

Adopts a connection to a queue manager.

void

connect(MQQueueManager qmanagerP, String targetQueue, String targetQmanager)

Adopts a connection to a queue manager and specifies a target queue and queue manager.

void

connect(String qmanagerP)

Establishes a bindings connection to a queue manager.

void

connect(String hostP, int port, String channelP)

Establishes a client connection to a queue manager.

void

connect(String hostP, int port, String channelP, String targetQueue, String targetQmanager)

Establishes a client connection to a queue manager and specifies a target queue and queue manager.

void

connect(String qmanagerP, String targetQueue, String targetQmanager)

Establishes a bindings connection to a queue manager and specifies a target queue and queue manager.

void

disconnect()

Frees queue manager resources, and drops the current queue manager connection.

int

getCommandLevel()

Returns the command level.

int

getExpiry()

Returns the expiry time in seconds.

static com.ibm.mq.jmqi.JmqiEnvironment

getJmqiEnv()

Get the Base Java JMQI environment, in order to allocate JMQI structures

String

getModelQueueName()

Returns the name of the model queue used as the basis of the agent's temporary dynamic queue for replies.

int

getPlatform()

Returns the platform on which the queue manager is running.

String

getQManagerName()

Returns the name of the queue manager (if connected).

String

getReplyQueueName()

Returns the name of the reply queue for PCF responses (if connected).

String

getReplyQueuePrefix()

Returns the string used as the first part of the agent's reply queue name.

int

getWaitInterval()

Returns the wait interval in seconds.

MQMessage[]

send(int command, PCFParameter[] parameters)

Sends a PCF query to the connected queue manager and returns the response.

void

setCharacterSet(int ccsid)

Sets the CCSID used in the message descriptor of request and response messages.

void

setEncoding(int encoding)

Sets the encoding used in the message descriptor of request and response messages.

void

setModelQueueName(String name)

Sets the name of the model queue used by the agent to create its reply queue, which is a temporary dynamic queue.

void

setReplyQueuePrefix(String prefixP)

Sets the string used as the first part of the agent's reply queue name.

void

setWaitInterval(int seconds)

Set the wait interval and expiry for PCF responses.

void

setWaitInterval(int wait, int expiry)

Set the wait interval and expiry for PCF responses.

Methods inherited from class com.ibm.mq.jmqi.JmqiObject
getJmqiEnvironment

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details
- MAXIMUM_ALLOWED_PREFIX_LENGTH
  
  public static final int MAXIMUM_ALLOWED_PREFIX_LENGTH
  See Also:
  
  Constant Field Values
- replyQueueName
  
  public String replyQueueName
  
  Deprecated.
  Use getReplyQueueName instead.
  See Also:
  
  getReplyQueueName()
Constructor Details
- PCFAgent
  
  public PCFAgent()
  
  Default constructor. Initializes a new PCFAgent with no queue manager connection.
- PCFAgent
  
  public PCFAgent(MQQueueManager qmanager) throws MQDataException
  
  Initializes a new PCFAgent with an existing queue manager connection.
  
  Parameters:
  
  qmanager - an existing queue manager connection
  
  Throws:
  
  MQDataException - if the queue manager cannot be accessed
- PCFAgent
  
  public PCFAgent(String host, int port, String channel) throws MQDataException
  
  Initializes a new PCFAgent with a client connection to a queue manager.
  
  Parameters:
  
  host - the hostname or IP address where the queue manager resides - default (if null or empty string) "localhost"
  
  port - the port on which the queue manager listens for incoming channel connections
  
  channel - the client channel to use for the connection - default (if null or empty string) "SYSTEM.DEF.SVRCONN"
  
  Throws:
  
  MQDataException - if the connection cannot be established
- PCFAgent
  
  public PCFAgent(String qmanager) throws MQDataException
  
  Initializes a new PCFAgent 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
- getJmqiEnv
  
  public static com.ibm.mq.jmqi.JmqiEnvironment getJmqiEnv()
  
  Get the Base Java JMQI environment, in order to allocate JMQI structures
  
  Returns:
  
  the JMQI environment
- connect
  
  public void connect(MQQueueManager qmanagerP) throws MQDataException
  
  Adopts a connection to a queue manager.
  
  Parameters:
  
  qmanagerP - an existing queue manager connection
  
  Throws:
  
  MQDataException - if the queue manager cannot be accessed
- connect
  
  public void connect(MQQueueManager qmanagerP, String targetQueue, String targetQmanager) throws MQDataException
  
  Adopts a connection to a queue manager and specifies a target queue and queue manager.
  
  Parameters:
  
  qmanagerP - an existing queue manager connection
  
  targetQueue - the target queue name
  
  targetQmanager - the target queue manager name
  
  Throws:
  
  MQDataException - if the queue manager cannot be accessed
- connect
  
  public void connect(String hostP, int port, String channelP) throws MQDataException
  
  Establishes a client connection to a queue manager.
  
  Parameters:
  
  hostP - the hostname or IP address where the queue manager resides - default (if null or empty string) "localhost"
  
  port - the port on which the queue manager listens for incoming channel connections
  
  channelP - the client channel to use for the connection - default (if null or empty string) "SYSTEM.DEF.SVRCONN"
  
  Throws:
  
  MQDataException - if the connection cannot be established
- connect
  
  public void connect(String hostP, int port, String channelP, String targetQueue, String targetQmanager) throws MQDataException
  
  Establishes a client connection to a queue manager and specifies a target queue and queue manager.
  
  Parameters:
  
  hostP - the hostname or IP address where the queue manager resides - default (if null or empty string) "localhost"
  
  port - the port on which the queue manager listens for incoming channel connections
  
  channelP - the client channel to use for the connection - default (if null or empty string) "SYSTEM.DEF.SVRCONN"
  
  targetQueue - the target queue name
  
  targetQmanager - the target queue manager name
  
  Throws:
  
  MQDataException - if the connection cannot be established
- connect
  
  public void connect(String qmanagerP) throws MQDataException
  
  Establishes a bindings connection to a queue manager.
  
  Parameters:
  
  qmanagerP - the queue manager name
  
  Throws:
  
  MQDataException - if the connection cannot be established
- connect
  
  public void connect(String qmanagerP, String targetQueue, String targetQmanager) throws MQDataException
  
  Establishes a bindings connection to a queue manager and specifies a target queue and queue manager.
  
  Parameters:
  
  qmanagerP - the queue manager name
  
  targetQueue - the target queue name
  
  targetQmanager - the target queue manager name
  
  Throws:
  
  MQDataException - if the connection cannot be established
- disconnect
  
  public void disconnect() throws MQDataException
  
  Frees queue manager resources, and drops the current queue manager connection. If the queue manager connection was established externally and passed by the caller using either the PCFAgent(MQQueueManager) constructor or the connect(MQQueueManager) method, the PCFAgent assumes the queue manager connection is externally managed and leaves the originator to disconnect it. If the PCFAgent established the queue manager connection itself, it disconnects the queue manager by invoking its disconnect() method.
  
  Throws:
  
  MQDataException - if there is a problem disconnecting
- send
  
  public MQMessage[] send(int command, PCFParameter[] parameters) throws MQDataException, IOException
  
  Sends a PCF query to the connected queue manager and returns the response. An MQCFH is generated for the request, containing the specified command identifier and appropriate parameter count.
  
  Parameters:
  
  command - the PCF command identifier
  
  parameters - an array of integer or string parameter or parameter array structures (type MQCFIN, MQCFIL, MQCFST or MQCFSL).
  
  Returns:
  
  an array of PCF response messages. A single PCF request can generate multiple replies.
  
  Throws:
  
  MQDataException - if there is a problem with the request or response
  
  IOException - if there is a problem with reading or writing
- setWaitInterval
  
  public void setWaitInterval(int seconds)
  
  Set the wait interval and expiry for PCF responses. The wait interval determines how long the agent will wait for response messages after issuing a request, and the expiry value specifies how long the request and response messages live before being expired by the queue manager. The default is 30s. Zero is allowed; negative values are ignored.
  Applying the same value for wait interval and expiry (which this method does) is normally appropriate; once the agent has given up hope of seeing any responses (as controlled by the wait interval), we want any surviving request and response messages to disappear (controlled by the expiry time).
  NOTE: APAR IT11161 reports an issue where the PCF responses will never expire. In order to ensure that PCF responses expire correctly, the Java system property:
  -Dcom.ibm.mq.pcf.enablePCFResponseExpiry=true
  needs to be set on the Java runtime environment that the PCFAgent is running in.
  Be aware that enabling PCF response expiry (so that PCF responses now expire as expected) might result in application changes being required, as the responses could expire before the PCFAgent has been able to process them.
  Parameters:
  
  seconds - the wait interval and expiry time in seconds
  
  See Also:
  
  setWaitInterval(int, int)
- setWaitInterval
  
  public void setWaitInterval(int wait, int expiry)
  
  Set the wait interval and expiry for PCF responses. The wait interval determines how long the agent will wait for response messages after issuing a request, and the expiry value specifies how long the request and response messages live before being expired by the queue manager. The default for each value is 30s. Zero is allowed; negative values are ignored.
  In circumstances where individual PCF requests produce large numbers of response messages, it can be helpful to use a larger value for expiry than for wait interval. This allows the agent sufficient time to process all response messages before they expire, while still noticing quickly if responses fail to appear.
  NOTE: APAR IT11161 reports an issue where the PCF responses will never expire. In order to ensure that PCF responses expire correctly, the Java system property:
  -Dcom.ibm.mq.pcf.enablePCFResponseExpiry=true
  needs to be set on the Java runtime environment that the PCFAgent is running in.
  Be aware that enabling PCF response expiry (so that PCF responses now expire as expected) might result in application changes being required, as the responses could expire before the PCFAgent has been able to process them.
  
  Parameters:
  
  wait - the wait interval in seconds
  
  expiry - the expiry time in seconds
- getWaitInterval
  
  public int getWaitInterval()
  
  Returns the wait interval in seconds.
  
  Returns:
  
  the wait interval
- getExpiry
  
  public int getExpiry()
  
  Returns the expiry time in seconds.
  
  Returns:
  
  the expiry time
- getQManagerName
  
  public String getQManagerName()
  
  Returns the name of the queue manager (if connected).
  
  Returns:
  
  the queue manager name
- getReplyQueueName
  
  public String getReplyQueueName()
  
  Returns the name of the reply queue for PCF responses (if connected). Applications may wish to exclude this queue from reports etc. The queue name is dynamically assigned when the agent connects.
  
  Returns:
  
  the queue manager name
- setEncoding
  
  public void setEncoding(int encoding)
  
  Sets the encoding used in the message descriptor of request and response messages. The default value is MQC.MQENC_NATIVE.
  
  Parameters:
  
  encoding - the numeric encoding
- setCharacterSet
  
  public void setCharacterSet(int ccsid)
  
  Sets the CCSID used in the message descriptor of request and response messages. The default value is MQC.MQCCSI_Q_MGR.
  
  Parameters:
  
  ccsid - the character set identifier
- getPlatform
  
  public int getPlatform()
  
  Returns the platform on which the queue manager is running. The integer returned is one of the MQPL_* constants defined in CMQC.
  
  Returns:
  
  the platform on which the queue manager is running
- getCommandLevel
  
  public int getCommandLevel()
  
  Returns the command level.
  
  Returns:
  
  the command level
- getReplyQueuePrefix
  
  public String getReplyQueuePrefix()
  
  Returns the string used as the first part of the agent's reply queue name. By default, this string is empty and the agent's reply queue name is generated entirely by the queue manager.
  Returns:
  
  The reply queue prefix
  
  See Also:
  
  setReplyQueuePrefix(String)
- setReplyQueuePrefix
  
  public void setReplyQueuePrefix(String prefixP)
  
  Sets the string used as the first part of the agent's reply queue name. The reply queue used by the PCFAgent is a temporary dynamic queue. By default, the reply queue prefix used by the PCFAgent is the empty string (""). When this is used, the name of the reply queue is generated entirely by the queue manager. If the method is called with a prefix specified, then the PCFAgent will pass that prefix to the queue manager whenever it needs to create a temporary queue. The queue manager will then generate the rest of the temporary queue name. This means that the queue manager generates a unique name, but the PCFAgent still has some control. The prefix specified should be fewer than 33 characters. If the prefix contains 33 characters or greater, then this method will truncate the prefix to be 32 characters in length. If the prefix does not contain an asterisk (*) character at the end, then an asterisk will be added to the end.
  
  Parameters:
  
  prefixP - The prefix value to be set
- getModelQueueName
  
  public String getModelQueueName()
  
  Returns the name of the model queue used as the basis of the agent's temporary dynamic queue for replies. By default, the system default model queue (SYSTEM.DEFAULT.MODEL.QUEUE) is used.
  
  Returns:
  
  The model queue name
- setModelQueueName
  
  public void setModelQueueName(String name)
  
  Sets the name of the model queue used by the agent to create its reply queue, which is a temporary dynamic queue. If the argument is null, the system default model queue (SYSTEM.DEFAULT.MODEL.QUEUE) is used. Setting the model queue name takes effect on the next connect operation.
  Parameters:
  
  name - The model queue name to set
  
  See Also:
  
  getModelQueueName()

Class PCFAgent

Field Summary

Fields inherited from class com.ibm.mq.jmqi.JmqiObject

Constructor Summary

Method Summary

Methods inherited from class com.ibm.mq.jmqi.JmqiObject

Methods inherited from class java.lang.Object

Field Details

MAXIMUM_ALLOWED_PREFIX_LENGTH

replyQueueName

Constructor Details

PCFAgent

PCFAgent

PCFAgent

PCFAgent

Method Details

getJmqiEnv

connect

connect

connect

connect

connect

connect

disconnect

send

setWaitInterval

setWaitInterval

getWaitInterval

getExpiry

getQManagerName

getReplyQueueName

setEncoding

setCharacterSet

getPlatform

getCommandLevel

getReplyQueuePrefix

setReplyQueuePrefix

getModelQueueName

setModelQueueName