Report Queue

All MillenniumReporting is handled through a reporting Queue. The Queue acts as a manager for the run of reports. It holds the schedule of when the report will be run and then where it will be published. Your institution may establish multiple Queues within Millennium, in order to distribute the task of running reports to a variety of computers to most effectively manage your institution's resources. At the same time that the Queues are defined, we suggest that a set of policies or guidelines should be established to help reporting operators know the conditions under which the various Queue(s) should be used.

Background Information

The Reporting Queue is a program that may be located on any computer with an ODBC driver and access to the Millennium database. The Queue's function is to monitor the Run Options that you have chosen for the report, and to signal the Queue to launch that run at the appropriate time. The Queue can also be run as Service. This eliminates the need for an operator to log onto the machine that hosts the Queue, following a reboot, in order to activate the Queue. Please reference the Software Environment document on the installation CD provided to you for a list of approved Reporting Servers.

Queues are "defined" in rows in the report_servers table. This table is located in the millreports database if you are a SQL site, or the millreports tablespace if you are an Oracle site. This table will store the name of the Queue, the name of the one Report Server that is to be used by that Queue, and also the name of one export database and Millennium database, both of which must be located on the designated Report Server. These identify the components that will be used for the run of the report. This Queue information is maintained by your system administrator. Your site may have multiple Queues set up so that report processing may be distributed.

The Millennium database (milldata - or the name your institution uses) is the location of the complete set of data tables that contains all constituent information.

The Millreports database (millreports) is the location of all report criteria definitions that you have created.

A Report Server is the location where the actual selection portion of the work is done when a report is run. The Queue "monitors" the process, sending the instructions to the Report Server in order to compare the Millennium data to the selection criteria and other specifications in the report, to determine whether a constituent's data passes or fails the selection process.

Report Servers may be located on any computer that is running SQL Server. An Millennium database (or a copy), and an export work database (or a copy) must be in place on the same computer for each Report Server. Each Report Server may deliver results to a designated set of printers, as defined in the report_printers table in the Millreports database/tablespace. It is possible for a system to have multiple report servers that are networked together, but each must meet the conditions described here.

Queue Settings

The Millennium Reporter's Queue provides you several functions.

• You may assign a report to run on a particular Queue (and therefore a particular Report Server) so that you can make efficient use of your resources.
• You may set up a time and date for some time in the future that you want to have a report begin its run instead of running it immediately. This also allows for more efficient use of the available resources.
• You may schedule a report to run at a specified interval (daily, weekly, bi-weekly, monthly). This allows you to send the report to the Queue only once, but then have it run repeatedly according to the schedule.
• You may assign a priority level to each report for its run so that you can determine which reports will take precedence if there is competition for resource time.

When you begin the run of a report, the Run Options form will be presented, so that you can specify several settings and preferences for that report's run. The first of these is the choice of the Queue that you want to use to manage the run of the report. Additional options on that form are actually instructions that the Queue will use to determine the timing, priority and destination for the report. Refer to the Run Options topics of Reporting Queue, Destination, and Priority for complete details.

Queue Management

Once reports have been submitted to the Queue via the Run Options form for a report, the contents of the Queue can be viewed and edited via the Millennium Explorer Q(ueue) Management item. Click the Q Management item to display a list of the Queues that are available to you. Select a Queue name to display the link from which you can view the history log for the selected Queue and the link that refreshes the current display of the reports that have been submitted to the Queue and are in the process of running, or waiting to be run. If you are logged on as the system administrator, you will also have a link that allows you to clear the history log for the selected Queue. Beneath these links will be a informational display of the reports that are currently running and the reports that are waiting to be launched by the Queue.

Note: The displayed list of Queues will pop up in a new window, allowing you to perform other tasks in Millennium.

Queue History

Millennium maintains a log of the activity for each Queue. The log is named reports.log and it is physically located on the machine that hosts the Queue, in the Queue directory. The log is a text file with an entry for each report that has been launched by the Queue and run to completion (whether successfully or not), and shows some information about each report's run. Users may view this log from within the Millennium interface by selecting the Q Management item in Millennium Explorer and then follow the Click here to view the report history for this queue hyperlink. All reports that have been run on the Queue, since the last time the log was cleared, will be listed. The last report run will be listed at the bottom of the log.

The log as displayed within Millennium will have identical refresh report history links at the top and at the bottom of the display. For those who use an Internet Explorer browser, clicking this link will automatically direct you to the bottom of the log display. Safari users will be automatically directed to the top of the display and when scrolling to the bottom. and selecting Click here to refresh the report history for this Queue. It will once again redirect you back to the top of the screen.

For each report launched by the Queue and run to completion, the Queue history log will contain the following information.

Report Name - The name of the saved report criteria.

User - The user for whom the report was run.

Run Date - The Date and time when the report was run.

Notes - The results of the run (whether or not it successfully completed), and the number of data rows that were selected.

If a report does not run to completion, the log will then list many of the reasons why the report may have failed to complete. If the run failed while Crystal Reports was in the process of formatting the data, an additional log will contain further details. This log is named cmdcrystal.log if you are running the Queue as a Service, or named Runcrystal.log if you are not, and it too is located in the Queue directory on the machine that hosts the Queue.

The history log will contain information about all reports that have been launched and run by the Queue until or unless it is cleared by the system administrator. Once the history log is cleared, information about these reports is deleted, and the log will automatically begin again once another report is launched.

Queue Information

The information about each report that is currently running, or waiting to be launched, will be shown in a format that is reminiscent of the display of data rows in the Profiles World. Each set of report information is separated from the next set by a wavy divider line. Some of the information that is displayed is a review of the settings that were chosen on the report's Run Options form, and, under certain circumstances, those settings may be edited. Other information displays the status of the run of the report. Yet other information is for reference purposes.

For each report submitted to the Queue but not yet run to completion, the following will display:

Report Name - The name of each report appears as the header or label for the set of information that appears in the Queue Management page.

Submitted Date - This is the date and time that the report was sent to the Queue. This information is automatically generated by the system and may not be edited. It continues to show the original date, even if edits are made to the settings.

Submitted for - This is the User ID identified as the 'Run for' user in the Run Report options.

Priority - This is the priority level (low, mid, or high) that was assigned via the Run Options form. If a Run After date was chosen, this item will be na (not applicable). This information may be edited by the user who originally submitted the report to the Queue or by the system administrator.

Frequency - This is the frequency schedule with which the report should be run, beginning with the Start Date and Time. This information may be edited by the user who originally submitted the report to the Queue or by the system administrator. See the topic, Run Frequency.

Start Date - This is the Start (after) Date that was assigned via the Run Options form. If a priority level was chosen, this item will be na (not applicable). This information may be edited by the user who originally submitted the report to the Queue or by the system administrator.

Start Time - This is the Start (after) Time that was assigned via the Run Options form. If a priority level was chosen, this item will be na (not applicable). This information may be edited by the user who originally submitted the report to the Queue or by the system administrator.

Server - This is the name of the Report Server that is defined as one of the components of this Queue. This item is for reference purposes only and may not be edited here.

Status - This information tells the current status of the run of this report. This includes whether or not it is actively processing, and if so, the stage of completion. This information is automatically generated by the system, but may be edited (in certain circumstances) by the user who originally submitted the report to the Queue or by the system administrator. See the topic, Run Status.

Millennium Database - This is the name of the Millennium database that is located on the designated report server and defined as a component of this Queue. This information is for reference purposes only, it may not be edited here.

Destination - This is the destination for the results of the run of the report (printer, export or HTML) that was assigned via the Run Options form. This information may be edited by the user who originally submitted the report to the Queue or by the system administrator.

If you select Export as your Destination from the aforementioned Run Options form you will also see:

Export To - This will always show Disk File, showing you that you have selected one of the items from the Export drop down list on the Run Options form.

Filename - This will show the path and filename that you typed in for the UNC path and filename on the previous form.

Edit the Queue

Once a report has been placed on a Queue, certain of the settings may be changed, but that must be accomplished via the Queue Management page. That page is accessed via the Q Management item in the Millennium Explorer. When you click on that item, the display frame to the right will display a list of the Queues that are available at your institution. You may examine the contents of any of the Queues by clicking its name in the list. You will be given a Queue Management display page, showing information about each of the reports on that Queue.

If your User ID (or the current user's) matches the Submitted By User ID for any of the reports, or if you are logged in as the system administrator, that report information will be accompanied by an Edit function button to the left. Reports that were placed on the Queue by any other user will be displayed, but without the Edit button, since they are unavailable to you for that purpose.

Edits to a report's Queue settings may only be performed while the report's Status is "idle"(waiting to be run). Therefore, if the report is "Idle" and the Edit button is shown, then the Queue settings for that report may be edited. When you click on the Edit button, you will be given a "condensed" version of the Run Report form, showing the settings that were previously chosen. These settings may be changed as you want.

Note that if a report status shows as "3rd party", this indicates that the process has already been handed off to the formatting software. Any change that you want to make at that point can only be performed via that software, not through the Millennium Reporter directly. If you edit or delete a report from the Queue while the "3rd party" status is showing, those edits or the deletion will only take effect for any future runs of the report.

To Edit Queue Settings

1. In the Millennium Explorer, click on Q Management. From the list of available Queues, click on the appropriate one. You will be shown a display page, containing a set of information for each of the reports on the Queue. Scroll to the appropriate report. Click the Edit button to the left. (If no Edit button appears, your User ID does not match the Submitted By User ID. See your system administrator.)
2. To edit the Destination, click on the desired radio button. If the Destination is "Printer" and you want to edit the choice of printers, click on the down arrow to the right of the printer list box and then click on the desired printer.
3. To edit the Priority, click on the desired radio button, Low, Mid, or High.

4. To edit the Run After date, verify that the Run After radio button is selected. Use the single arrow buttons to scroll the calendar forward or backward a month at a time, or the double arrows to scroll a year at a time, until the desired Start Date is in view. Click that day in the calendar display to highlight it and then click on the Add button to place that date in the text box to the right.

   OR

   Position the cursor in the date text box and then type in the Start After date.

5. To edit the Time After which it will begin to run, click in the Time text box and then type in the desired time. Verify that the appropriate AM or PM radio button is activated.
6. To edit the Frequency with which the report will be run, click on the arrow to the right of the list box to display the standard schedules. Click the desired frequency. Note that the report will run at the interval you choose, beginning with the Start Date you indicated.

7. When all of the report's settings appear as you intend, click on the Update button to register the changes

   OR

   Click Cancel to leave the settings as they were when you first accessed the Queue Management display.

Remove a Report from the Queue

The options for removing or deleting a report from the Queue vary, depending on the Status of the report at the time you want to remove it.

If the report is in the process of selecting data rows, building the export work table, or is paused during one of those steps at the time that you want to delete it, you must remove it by using the Stop Report hypertext at the bottom of the display of that report's information. If this is the situation, the Status will change to "Stopping" as it finishes executing the current criteria statement, and then the report will be removed from the Queue. Note that the system will launch additional reports (as appropriate) as soon as the status of a report becomes "Stopping".

To Remove a report that shows a percentage of completion, or "Paused" as the Status, click on the hypertext message at the bottom of the report information that reads, "Stop Report". (Note that if the report was set to run on a scheduled frequency, it will no longer do so, since it will have been removed from the Queue.)

To Remove a report that shows a Status of "idle", or "editing", click on the Edit button. At the bottom of the Edit form, click on the Delete button to remove the report from the Queue. Note that if the report was set to run on a scheduled frequency, it will no longer do so, as it will have been removed from the Queue. Also note that if you delete a report from a Queue that is not open at the time of the deletion, the Queue Management display will continue to show that report until the Queue is opened and the deletion instruction can be carried out.)

Pause/Resume a Report

To Pause a report that shows a status of 'Running', or some other Millennium progress status (such as Remove Deceased), click the Edit button to the left of the desired report. At the bottom of the Edit form, click the 'Pause Report' hyperlink.

To Resume running a paused report (the status shows 'Paused'), click the Edit button located to the left of the desired report. At the bottom of the Edit form, click the 'Resume Running Report' hyperlink.

Run Frequency

If you want to have the report run on a regular schedule without the need to send it to the Queue each time it is to be run, you may indicate this on the Run Options form when the report is first placed on the Queue. This is done by choosing one of the standard frequency schedules in that form. When this is done, the report will remain on the Queue until it is removed via Q(ueue) Management editing techniques. See Run Options, Priority for more information.

Run Status

The Run Status for a report on the Queue describes the action (if any) that is taking place with that report at the time that you accessed the Queue Management display page. The information is dynamic, so if the status changes while you are viewing that page, the Status information will also change. The following list shows the possible "statuses" that may be shown and the condition each represents.

Idle - This indicates that the report is on the Queue and waiting for the appropriate time so that it may begin to run.

Editing - This indicates that the report has been accessed in an Edit mode (probably by another user) and therefore will not run until that process has been completed and the Edit mode has been closed.

Percentage - If the report is actively processing, the Status will show a numerical percentage of completion. This percentage refers to the selection and creation of the export work table, only. The formatting portion of the process is not included in the percentage of completion time estimate.

3rd Party - This indicates that the report selection and export creation is complete and that the formatting software (such as Crystal - a 3rd party product) is performing its part of the reporting process.

Paused/Pausing - This indicates that the command has been given to temporarily stop the run of the report, to be resumed when the operator signals again. When such a command has been issued, the system will complete the current selection statement that it is processing and then pause. Thus, if a statement is executing when the Pause command is given, the Status will describe that condition as "Pausing". When that select statement is complete, the report will come to a complete Pause and the Status will be changed to "Paused".

Stopped/Stopping - This indicates that the command has been given to stop the run of the report. When such a command has been issued, the system will complete the current selection statement that it is processing and then stop, and delete the report from the Queue. Thus, if a select statement is executing when the Stop command is given, the Status will describe that condition as "Stopping". When that select statement is complete, the report will come to a complete Stop and the Status will be changed to "Stopped". This information will appear very briefly and then the report will be removed from the Queue. The Queue will look for the next Low Priority report to launch (in accordance with the Queue option that is in effect regarding Low Priority reports) as soon as the previous one has a Status of "Stopping".

Finished - This indicates that the report has been run and formatted and delivered to the appropriate destination. This status appears very briefly before the entire set of report information is automatically removed from the Queue Management display page.

Queue.exe

queue.exe is the Reporting Queue program installed on the machine that will host the Queue. The location of queue.exe, for a particular Reporting Queue, is specified to Millennium when the Queue is created (defined) by the system administrator, via the MillenniumSystem Info page.

To physically access the queue.exe program, you must be on the Queue machine itself. Via the Report item on the queue.exe menu bar, you may Stop, Pause, Resume and/or Delete a report that has been submitted to the Queue; however, refer to Removing a Report from the Queue, above, for important caveats regarding these functions.

Via the Option item on the queue.exe menu bar, you may restrict the run of Low priority reports to one at a time by clicking the Low Priority 1x menu item to place a check mark next to it. If this menu item is left unchecked, the Queue can execute multiple Low priority reports simultaneously.

Typically, non-system administrator Millennium users will not have access to queue.exe, and will therefore utilize Q(ueue) Management to Stop, Pause, Resume or Delete a report.

Install and Run the Queue As a Service

The following information describes the purpose and procedures for running a reporting Queue as a Windows Service. The Queue may also be run in the foreground (not as a service).

Millennium Queue Service

Milqueue.exe is the Millennium Queue Service. The Milqueue Service ensures that the Millennium Queue (Queue.exe) is always running on the Queue Machine. When the Queue operates as a service, the status does not display on the Windows task bar. The Millennium Queue Service will ensure that Queue.exe is always available for reports to run to successful completion.

Queue Administration Program

QueueAdmin.exe is the Queue Administration Program. It will be installed during the Millennium Reporting Queue Installation. The default location of the Queue directory is C:\QUEUE. This is where QueueAdmin.exe will reside. The purpose for QueueAdmin.exe is to install and maintain the Milqueue service.

For the Milqueue service to properly execute, the QueueAdmin program must use a User Account to initialize the Milqueue Service. The QueueAdmin program will maintain this User Account, either on a domain, or in Local computer accounts. The decision as to whether the User be created in a domain or locally should be based on the configuration of the Millennium servers.

Depending on the choice of Domain or Local accounts, the Queue Admin program will create the User as necessary, and verify that the Milqueue Service is properly installed and running. The User Account will be created with only the privileges needed to execute the Milqueue service. It is recommended that this User Account be used only for the purpose of running the Milqueue service.

Installing the Millennium Queue Service:

1. Login into the Queue Machine as an Administrator. If you are going to create accounts on more than one machine at the same time, then you need to log on as user with Domain Admin privileges.
2. Install the Reporting Server software using the Millennium Installation CD.
3. On the Queue Server, locate the Queue Installation Directory, usually C:\QUEUE.
4. From the directory, run QueueAdmin.exe. If using VISTA, you must right-mouse click and run as Administrator.
5. Click the New User button. If a Local Account is to be created, leave the Compute Name radio button set, and proceed to Step 6. If a Domain Account is to be created, change the radio button option to Domain, and enter the name of the Domain.
6. Enter a User Name.
7. Enter a Password.
8. If a Domain Account is to be created, proceed to Step 9. If a Local Account is to be created, enter the IIS Server Name in the Additional Computer field. The intention here is create the Queue User on the IIS so they have access to write reports to the IIS Server.
9. Click OK.
10. Verify the password by typing it again and clicking OK.
11. The Queue Admin program will create the users as necessary and report success or failure via a Message Box. If the Local Account option is chosen, two Message Boxes will appear, confirming the creation of the Queue Account and the IIS Account. Click OK to close the Message Box.
12. Upon returning to the Queue Admin Dialog Box, the User Name and Password fields will change, based on the New User that was created. Verify that the Install the Millennium Queue Service radio button is selected. Click OK to Install the Queue Service. A status bar above the OK button will display certain Status messages. After the service has been installed, a Message Box will appear stating the successful completion on the Queue Service Installation. Click OK, and the Queue Admin program will close. At this time, the Queue Service will start, and the Queue will become available for reporting.

Changing the Queue User Password:

1. Login into the Queue Machine as an Administrator.
2. On the Queue Server, locate the Queue Installation Directory, usually C:\QUEUE.
3. From the directory, run QueueAdmin.exe
4. Click the Change Password button. If a Local Account is to be changed, leave the Computer Name option set, and proceed to step 5. If a Domain Account is to be changed, change the radio button option to Domain, and enter the name of the domain.
5. Enter the Current Password of the User.
6. Enter the New Password of the User.
7. If a Domain Account is being modified, proceed to Step 9. If a Local Account is to be created, enter the IIS Server Name in the Additional Computer field. The intention here is make the User change to the Queue account and the IIS Server account at the same time.
8. Click OK.
9. Verify the New Password by typing it again and clicking OK.
10. The Queue Admin program will modify the users as necessary and report success or failure via a Message Box. If the Local Account option is chosen, two Message Boxes will appear, confirming the modification of the Queue Account and the IIS Account. Click OK to close the Message Box.
11. Upon returning to the Queue Admin Dialog Box, the User Name and Password fields will change, based on the new User information. Verify that the Reset the Millennium Queue Service radio button is selected. Click OK to Install the Queue Service. A status bar above the OK button will display certain Status messages. After the service has been installed, a Message Box will appear stating the successful completion on the Queue Service Installation. Click OK, and the Queue Admin program will close. At this time, the Queue Service will restart, and the Queue will become available for reporting.

Creating a New Queue User for an Existing Queue Installation:

1. Login into the Reporting Server (Queue Machine) as an Administrator.
2. On the Queue Server, locate the Queue Installation Directory, usually C:\QUEUE.
3. From the directory, run QueueAdmin.exe
4. Click the New User button. If a Local Account is to be created, leave the Computer Name radio button set, and proceed to Step 5. If a Domain Account is to be created, change the radio button option to Domain, and enter the name of the Domain.
5. Enter a User Name.
6. Enter a Password.
7. If a Domain Account is to be created, proceed to Step 8. If a Local Account is to be created, enter the IIS Server Name in the Additional Computer field. The intention here is create the Queue User on the IIS so they have access to write reports to the IIS Server.
8. Click OK.
9. Verify the password by typing it again and clicking OK.
10. The Queue Admin program will create the users as necessary and report success or failure via a Message Box. If the Local Account option is chosen, two Message Boxes will appear, confirming the creation of the Queue Account and the IIS Account. Click OK to close the Message Box.
11. Upon returning to the Queue Admin Dialog Box, the User Name and Password fields will change, based on the New User that was created. Verify that the Install the Millennium Queue Service radio button is selected. Click OK to Install the Queue Service. A status bar above the OK button will display certain Status messages. After the service has been installed, a Message Box will appear stating the successful completion on the Queue Service Installation. Click OK, and the Queue Admin program will close. At this time, the Queue Service will start, and the Queue will become available for reporting.

System Details

C:\Queue\QueueAdmin.log is created after QueueAdmin.exe runs.

C:\Queue\Milqueue.log is created when milqueue.exe starts the Queue Service. If there is a log in failure, it will display here.

Registry Key HKEY_LOCAL_MACHINE\SOFTWARE\JSI FundRaising Systems, Inc.\Queue Service on the Reporting Server (Queue machine) will contain settings that milqueue.exe uses each time it starts.

Top of Page