com.ibm.mq.headers.pcf

Class PCFAgent

java.lang.Object

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:

PCFMessageAgent

Field Summary

Fields

Modifier and Type	Field and Description
static int	MAXIMUM_ALLOWED_PREFIX_LENGTH
java.lang.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 and Description
PCFAgent() Default constructor.
PCFAgent(MQQueueManager qmanager) Initializes a new PCFAgent with an existing queue manager connection.
PCFAgent(java.lang.String qmanager) Initializes a new PCFAgent with a bindings connection to a queue manager.
PCFAgent(java.lang.String host, int port, java.lang.String channel) Initializes a new PCFAgent with a client connection to a queue manager.

Method Summary

Modifier and Type	Method and Description
void	connect(MQQueueManager qmanagerP) Adopts a connection to a queue manager.
void	connect(MQQueueManager qmanagerP, java.lang.String targetQueue, java.lang.String targetQmanager) Adopts a connection to a queue manager and specifies a target queue and queue manager.
void	connect(java.lang.String qmanagerP) Establishes a bindings connection to a queue manager.
void	connect(java.lang.String hostP, int port, java.lang.String channelP) Establishes a client connection to a queue manager.
void	connect(java.lang.String hostP, int port, java.lang.String channelP, java.lang.String targetQueue, java.lang.String targetQmanager) Establishes a client connection to a queue manager and specifies a target queue and queue manager.
void	connect(java.lang.String qmanagerP, java.lang.String targetQueue, java.lang.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
java.lang.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.
java.lang.String	getQManagerName() Returns the name of the queue manager (if connected).
java.lang.String	getReplyQueueName() Returns the name of the reply queue for PCF responses (if connected).
java.lang.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(java.lang.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(java.lang.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 java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MAXIMUM_ALLOWED_PREFIX_LENGTH

public static final int MAXIMUM_ALLOWED_PREFIX_LENGTH

See Also:

Constant Field Values

replyQueueName

public java.lang.String replyQueueName

Deprecated. Use getReplyQueueName instead.

See Also:

getReplyQueueName()

Constructor Detail

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(java.lang.String host,
                int port,
                java.lang.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(java.lang.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 Detail

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,
                    java.lang.String targetQueue,
                    java.lang.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(java.lang.String hostP,
                    int port,
                    java.lang.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(java.lang.String hostP,
                    int port,
                    java.lang.String channelP,
                    java.lang.String targetQueue,
                    java.lang.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(java.lang.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(java.lang.String qmanagerP,
                    java.lang.String targetQueue,
                    java.lang.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,
                        java.io.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

java.io.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 java.lang.String getQManagerName()

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

Returns:

the queue manager name

getReplyQueueName

public java.lang.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 java.lang.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(java.lang.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 java.lang.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(java.lang.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()