Navigation:  Configuration and Setup > Message Queue Interfaces

CopiaFacts applications implement a number of optional interfaces to Microsoft Message Queues (MSMQ).  These are currently used for the following purposes:

The CopiaFacts MSMQ interface requires MSMQ version 2 or above.  It is therefore not supported on Windows NT, which provides only MSMQ version 1. Version 2 of MSMQ is the one that was introduced with Windows 2000.

MSMQ must be installed on each machine which will send or receive messages.  If not already installed, you can use the Control Panel Applet 'Add or Remove Programs' to install it, selecting 'Add/Remove Windows Components'  from the bar to the left of the list.  Select 'Message Queuing'.

Some knowledge of Windows configuration and management is required to create an efficient MSMQ environment. There is an extensive MSMQ information resource available from http://www.microsoft.com/windowsserver2003/technologies/msmq/default.mspx

All queues to be used by CopiaFacts must be created in advance.  This requires the use of the Microsoft Management Console (MMC), accessed by right-clicking My Computer and selecting Manage.  The MSMQ area is then under Services and Applications, Message Queueing, Private Queues.  Right-click this entry and and select New Private Queue to create a queue.

You may enter any queue name at this point.  The prefix 'copia' is suggested, so that for example the name entered for the preliminary FS File Queue feature might be:

copia_email_fs

A queue should normally be created locally on the machine which will be writing it.  However in some circumstances other queue locations will be more efficient.  Currently the CopiaFacts MSMQ interface has only been tested with Private queues.

When referencing the queue name in a CopiaFacts command or variable, it must be specified in full: the syntax for a local queue name would be for example:

.\private$\copianotify

.\private$\copia_email_fs

and for a remote queue name residing on machine 'mname' would be for example:

mname\private$\copiajoblog

Queues are currently only written with single transactions. However queues may be created with or without the Transactional attribute. If the queue is transactional, messages to it are written with the attribute MQ_SINGLE_MESSAGE.  Transactional queues increase security at the expense of some performance. Also note that transactional queues do not support message priority settings. Messages all have the same priority in a transactional queue and the priority specified in CopiaFacts is ignored.

You must ensure that the queue permissions are appropriate for the nodes that will be writing and reading them.  The permissions are set from the Security tab after right-clicking the queue name in the MMC and selecting Properties.

Note that the MMC has a limited display mode for actual queue messages.  It shows only the first couple of hundred messages in a queue, and it displays only the first couple of hundred bytes of a message body.  The message body display is a dump of the raw Unicode message content. The message counts do not auto-refresh and the display must be refreshed manually at the Private Queues level to see recently written messages.

The FS File Queue

The current implementation of FS file queues is a preliminary release.  It is limited to a single 'tosend' queue, and can be read by e-mail threads only.  CopiaFacts e-mail threads defined with ONLY an e-mail line operation will automatically read the queue until it is empty.  The principal benefit is a significant increase in throughput which comes about because the threads are in continuous use and do not have to wait for a new transaction to be found.  When there are no messages in the queue the threads are fed from FS files in the normal way.

To obtain maximum benefit from the use of an e-mail queue, it is best to suppress the writing of FS files to the SENT and FAIL folders (by using $delete_option) and to handle logging and accounting by another method.  Currently, the CopiaFacts Job Administration feature relies on the SENT and FAIL FS files to monitor and report on job items so in this environment the SENT and FAIL FS files need to be retained.

To use an FS File Queue for e-mail operations, you must either have an application which writes messages to the queue, or use FFBC which has an option to launch e-mail broadcast items to the queue.  After installing Microsoft Message Queuing (if necessary) as described in Pre-Requisites, create a private queue on the machine where the queue is to reside as described in Queue Properties.

The FS file queue name is currently specified to the CopiaFacts engine by using a configuration file $var_def with the name COPIA_FSQ, for example:

$var_def COPIA_FSQ mname\private$\copia_email_fs

FFBC will use the COPIA_FSQ definition if present, and if the broadcast is a plain e-mail broadcast with no fax-transmission alternatives.

If your own application is writing messages for this queue, the Label field must contain the unique FS filename (e.g. '12345678.FS') and the Message field must contain a complete FS file image, with lines separated by <cr><lf> in the usual way.

Note that if you specify retries for e-mail failures, they will not be handled in the queue, but instead will be written back to the normal TOSEND folders.  The threads which are allocated for e-mail only will not process these items until the queue is empty.  If you need the retries to be processed earlier than this, define a few threads with both e-mail and worker-box line operations.  These will not then participate in pulling FS images from the queue, but will be able to process e-mail items in TOSEND queues.

The Notify Queue

(documentation follows)

The Preproc Queue

(documentation follows)

The Job Log Queue

(documentation follows)

 

---

Topic url: http://www.copia.com/support/refmanual/index.html?message_queue_interfaces.htm