DumontEXE 0.0.1
Dumont Queue Category Definition

The Dumont Queue Category is a special category that is used by Dumont to Queue up various events within the Commence database so that it can process them sequentially. By using a Queue category, is is possible to have agents within Commence respond to various events, and cause actions to be taken on those events in a step by step manner.

One of the things that Commence agents do not offer is any sort of control over what agents get fired and in what order. Nor does it offer any sort of notification of when an agent actually completes so that the completion of one agent can signal the start of another agent.

This DumontQueue handler is designed to improve this situation. This queue handler watches for items that appear in the queue category asychronously, and processes them out of the queue one at a time. This object monitors the DumontQueue category for new items and when one appears it is pulled from the queue and processed. Each cmcQueue object that gets instantiated in the system begins monitoring the DumontQueue category immediately. As soon as an item in the Queue is recognized by the "Queue Name" value it is processed.

Processing an item in the queue is as simple as running a program and passing to it the listed arguments. The cmcQueue object waits until the called program completes before processing the next item in the Queue. If the called program opens a dialog window, or even a text editor, the processing of remaining queue items will be suspended until the dialog is closed, or the text editor is shut down.

The DumontQueue category is designed to be a category that can be easily loaded by an agent, knowing that the agents have somewhat limited functionality and limited access to information. By this I mean that Commence agents have limited access to fields from other categories, and they cannot generate their own dynamic values such as THID numbers, GUID numbers, sequence numbers, and various other values that would be very handy in in agent manipulation. Therefore, the DumontQueue is a category that allows duplicate items, allowing agents to load items into the queue without much concern over the naming of the item. All that the DumontQueue category items care about (for the most part) is the name of the program to run, and the arguments to pass to that program.

The DumontQueue category is defined as follows:

The DumontQueue Category Definition
 DumontQueue Category Definition
 --------------------------
 Name:          DumontQueue
 Clarify Field: none
 Separator:     " ~ "
 Index 1:       none
 Index 2:       none
 Duplicates:    Yes

  type        name             description
 +----------+----------------+--------------------------------------------------------
  Name      ' Item Name      ' required:  Name Field
  Memo      ' Arguments      ' required:  Program Argument List
  Number    ' Priority       ' required:  Program Prioritization
  Text(80)  ' Program        ' required:  Name of the program to run
  Text(40)  ' Queue Name     ' required:  Name of the Queue
  Memo      ' Result         ' blank:     Answer-back from the program
  Sequence  ' Sequence       ' automatic: Sequence which item was added to the queue
  Connect   ' pRWD->Employee ' required:  Assigned to which staff person (client)

Here is a Detailed description of those fields:

Item Name
  Type        Name             Kind
 +----------+----------------+----------
  Name      ' Item Name      ' REQUIRED
This field is the category 'Name' field. The value of this field is somewhat inconsequential since it does not get used for any function. An agent can assign a 'documentation' string such as: VNC-SC1 to (Initials%) (-Date-) (-Time-) The actual value of this string doesn't really matter, but can be used to document the queue item. Since the DumontQueue category allows duplicates, then the value of this field is allowed to repeat. Put whatever value in in here that you want.
Arguments
  Type        Name             Kind
 +----------+----------------+----------
  Memo      ' Arguments      ' REQUIRED
These are the arguments that will get sent to the Program. Each argument is to appear on a separate line from the previous. The argument list depends entirely on the requirements of the program being run. Here is an example of an argument list:
Queue Argument List Example
 C:\Commence\Scripts\OnChangeCalendar.vbs
 (%calendarGuid%)
 (%Date Start%)
 (%calendarKey%)
In the example shown above the first argument is the name of the program to run, the second argument gets passed to that program, and so on. In this example, the name of the program that is receiving these arguments is going to be 'wscript' (which we'll discuss later). So the first argument that gets passed to wscript is the name of the .vbs script that you want to run. The rest of the arguments shown are whatever arguments you want passed to the .vbs program. It's quite simple.
Priority
  Type        Name             Kind
 +----------+----------------+----------
  Memo      ' Priority       ' REQUIRED
This controls the priority of this queue item. Since a single queue can contain multiple items, it is possible to have a queue filled with hundreds of items to be processed. By setting a queue item priority it is therefore possible to insert an item for immediate processing above any other item merely by setting a smaller Priority number.
Program
  Type        Name             Kind
 +----------+----------------+----------
  Text(80)  ' Program        ' REQUIRED
This is the program to execute. In the case of .vbs script programs the name of the program should be 'wscript'. In the case of any other program you should make sure you specify the full path to the program that you want to run, if it is not in the path already. This means that for most regular programs, such as notepad and paint, no path needs to be specified.
Queue Name
  Type        Name             Kind
 +----------+----------------+----------
  Text(40)  ' Queue Name     ' REQUIRED
This is the name of the Queue. There is only one DumontQueue category, but there can be multiple Queue's in it. Each queue gets processed by its own cmcQueue object.
Result
  Type        Name             Kind
 +----------+----------------+----------
  Memo      ' Result         ' BLANK
It is possible to have a queue item get answered by the program that was run. For the time being this field is not used and should be left blank.
Sequence
  Type        Name             Kind
 +----------+----------------+----------
  Sequence  ' Sequence       ' Auto
This is a sequence number for the item. Each item gets its own automatic sequence number. This allows for sequential processing of queue items as they are placed into the queue.
pRWD->Employee
  Type        Name             Kind
 +----------+----------------+----------
  Connect   ' pRWD->Employee ' Required
This is a connection to the Employee (-Me-) item. This connection is required. Even though when items get added to the queue, they generally get added to the queue as 'local' items, it is important to connect them to the (-Me-). The cmcQueue object pulls items from the queue, and it pulls them based upon the name of the queue, the sequence number, and the connection to the (-Me-) item.
The reason for this is simple. Using the DumontQueue category, and by attaching the item to an employee throught the pRWD connection, it becomes possible to author a Queue item on one machine and publish it to another simply by making this connection. This is usually done on the server ~ the server authors an item and assigns it to a particular user, and when that user syncs-in that item it is processed immediately. This makes it possible to remotely launch programs on select clients from the Commence server.
Adding Items to the Queue
Items can be added to the DumontQueue either through an agent, or directly by scripting.
DumontQueueAgent.png
 All Classes Namespaces Functions Variables Enumerations Enumerator Properties




~ ~ ~ ~ ~ ~
Source Code without Comments is like a Cranberry Garland
without the berries. Comment your Code!
 
Commence Database User Support Group Forum
http://newsgroup.showoff-db.org/
~ ~ ~ ~ ~ ~
Author: Mark Petryk
Lorimark Solutions, LLC
mark@lorimarksolutions.com