Message Queue Interfaces
CopiaFacts applications implement a number of optional interfaces to Microsoft Message Queues (MSMQ). These are currently used for the following purposes:
|FS File Queue||This type of queue can be used to submit e-mail or SMS transactions consisting of FS file images to the CopiaFacts engine. Currently only a single incoming queue is supported.|
|Notify Queue||A customizable message can be written to this queue whenever a fax, e-mail or SMS transmission is completed. Messages can also be written to this queue when an incoming fax is manually routed in FFVIEWER.|
|Monitor Queue||A customizable message can be written to this queue at each stage of an individual fax transmission. This allows a customer-supplied application to read the queued messages and display real-time status information about the transmission.|
|Preproc Queues||These queues are used to submit prioritizing messages to FFEXTERN, to request that a specific FS file is processed next. This may be needed when FFEXTERN has a lengthy background task to perform.|
|Job Log Queue||When specified, messages are sent to this queue for each job history record written for a job instance.|
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 at the msdn.microsoft.com website: search for MSMQ.
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:
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:
and for a remote queue name residing on machine 'mname' would be for example:
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 current implementation of FS file queues is a preliminary release. It is limited to a single 'tosend' queue, which can be read by e-mail or by SMS threads only. CopiaFacts e-mail threads defined with ONLY an e-mail line or ONLY an SMS 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 FS file 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.
In the FS queue, TOSEND priorities 0 to 7 are translated to queue priorities 7 to 0 respectively, and TOSEND8 and above are translated to queue priority 0.
To use an FS File Queue for e-mail or SMS operations, you must have one of the following:
•a user-written application which writes messages to the queue
•FFBC, which has an option to launch e-mail broadcast items (not SMS) to the queue
•Job Administration with COPIAFACTS engine 7.354 or later, CF8JOBADM 7.367 or later and JOBMON 7.301 or later, which have an option to launch e-mail or SMS job items to the queue and disable end-job checking until the last job item has left the queue.
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
It is possible to condition this command in the configuration file using $if @NODEID = to define a different queue name for each node, for use with Job Administration. However FFBC does not support multiple nodename definitions, even if conditioned in this way.
FFBC will use the COPIA_FSQ definition if present, and if the broadcast is a plain e-mail broadcast with no fax-transmission alternatives.
Job Administration will use a job variable JOB_EMAIL_FSQ or JOB_SMS_FSQ to specify that the defined queue name is to be used for a particular job instance. This is only valid when used with a broadcast type EB or FEB1 (for e-mail) or SB (for SMS).
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 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 (or SMS) and worker-box line operations. These will not then participate in pulling FS images from the queue, but will be able to process items in TOSEND queues.
The Notify Queue
The Notify Queue name is specified on the $notify_qname command. When specified, the contents of the variables with names starting NQ_ are written to the queue at the end of each attempt or completed transaction. By defining the content to be expanded in these variables, you have full control over the data written in the message body and message label. Copia provides no application to read this queue.
The Monitor Queue
The Monitor Queue name is specified on the $monitor_qname command. When specified, CopiaFacts will look for an FS/USR/UJP variable named MONITOR_EVENTS. The value of this variable should be the name of another user variable which you will have defined elsewhere (e.g in FAXFACTS.CFG) to contain a comma-separated list of events. The 'events' can either be CopiaFacts state numbers or special board-specific codes designating stages of the fax transmission. As each event is reached, a message is written to the queue, formatted as specified in the variable MQM_MESSAGE_TEXT. By defining the content to be expanded in this variables, you have full control over the data written in the message body. Copia provides no application to read this queue.
The Preproc Queues
The Preproc Queue names are specified on the $preproc_qname and $preproc_altqname commands. When specified, FS files written into PREPROC directly by the job launcher have their filename written to the queue with an appropriate priority. This allows urgent preprocessing tasks such as Preview and PreConvert items to 'jump the queue' for work in an FFEXTERN Document Converter which may be processing a large number of lower priority tasks. The use of the alternate queue allows a second FFEXTERN instance to be controlled separately.
In the Preproc queues, TOSEND priorities 0 to 7 are translated to queue priorities 7 to 0 respectively, and TOSEND8 and above are translated to queue priority 0.
The Job Log Queue
The Job Log queue name is specified on the $joblog_qname command. When specified, the Job Administration log function writes a queue message for every item that is also written to a job log file (visible in the JOBADMIN job history pop-up window). This allows customer-written applications to monitor the progress of jobs.