In order to bring you the best possible user experience, this site uses Javascript. If you are seeing this message, it is likely that the Javascript option in your browser is disabled. For optimal viewing of this site, please ensure that Javascript is enabled for your browser.
Login  |   On Demand  |   Home  |   qad.com




Service Mode
Service mode is a continuously running Windows Service (called the QAD Reporting Framework Service) that runs reports as soon as they are scheduled. The service only processes reports that were scheduled with a special batch ID: a virtual batch named QADSVC. This special batch is called virtual because it does not need to be created using Batch ID Maintenance. However, you can create a batch named QADSVC using Batch ID Maintenance, in which case it appears on the list of available batch IDs in the scheduled report form (and is therefore visible to users).
The service is especially useful to support cases where the application that needs to run a report is not running in a QAD .NET UI process (for example, a Progress program running on a Linux machine). This service is also essential to the infrastructure of the new report bursting capability.
The service mode runs as a Windows Service on one or more Windows computers. Its architecture is similar to that of the batch mode: multiple server processes can be run on any number of machines for scalability and failover.
The QAD Reporting Framework Service is started using the standard Windows Services Manager tool (choose Control Panel|Administrative Tools). When started, a broker process is launched (QADReportingFrameworkService.exe), which in turn launches one or more agent processes (QAD.Client.exe). The agent processes perform the actual report execution. If the service is paused, the broker in turn pauses each agent. If the service is stopped, the broker terminates each agent process before terminating itself.
Note: When stopping or pausing the service, any agents that are currently running reports are not interrupted; the stop or pause command takes effect after the currently running report is completed. If a long-running report needs to be canceled, this can be accomplished using the QadRFSAdmin program, which is described below.
The underlying mechanism used to process reports in the Reporting Service is similar to that used by batch mode report servers. The configuration settings for report e-mail notifications, printers, and output file routing are shared for use in both server modes. Likewise, Scheduled Report Browse and Scheduled Report History Browse can be used to monitor service mode activity in the QADSVC batch.
There is one important difference in the behavior of Service Mode compared to Scheduled Batch Mode operation: the Run Once setting is ignored for Service Mode reports because they are always run only once. When a Service Mode report has been run successfully, its scheduled report record gets deleted (and therefore disappears from view on the Scheduled Report Browse).
Note: If a Service Mode report run fails, its status is changed to ERROR. Administrators can attempt a rerun of that report by changing the status back to NEW using Report Resource Maintenance. (They can navigate a link to this by right-clicking the ID field on Scheduled Report Browse.)
The installation of the QAD Reporting Framework Service is similar to that of a batch mode server since it is also bundled with the QAD .NET UI client installation. However, some additional configuration steps must be completed before starting the service, which are described in the next section.
The number of agent processes spawned by the service is specified in the configuration file. It is generally advised to have more than one agent running, so that if an agent is busy running a long report, other agents are available to process other reports simultaneously. If too many agents are running, the server machine may experience high CPU and/or memory usage, degrading its performance. If this occurs, modify the configuration file to define fewer agents and restart the service. For greater throughput and failover, several machines can be used, each one running a Reporting Framework Service against the same environment.
Note: The Reporting Framework Service broker communicates with its agents using interprocess communication (IPC) channels. The name of the channel used for a particular agent is determined by the agent’s name as chosen in the configuration file. These names must be unique on a given machine. When running Reporting Framework Services on multiple machines, however, it is OK to have the same agent name on different machines.
Setting Up QAD Reporting Framework Service
1
Install the QAD .NET UI client on the report server machine, which must be a Windows machine. Test the install by running the QAD .NET UI client and logging in.
2
Register the QAD Reporting Framework Service as a Windows Service:
Open a DOS command window (choose Start|Run, enter cmd, and click OK).
Navigate (cd) to the qad.plugin.reportserver plug-in directory (under the .NET installation plug-ins directory; typically in a location such as C:\Program Files\QAD\QAD Enterprise Applications 2012 EE\plugins\qad.plugin.reportserver)
Run install-qad-reporting-service.bat
The QAD Reporting Framework Service is now registered as a Windows Service.
3
Configure the server. This consists of entering some settings into the XML service configuration file:
From a DOS window or File Explorer, go to the config subdirectory under the qad.plugin.reportserver plug-in directory (typically in a location such as C:\Program Files\QAD\QAD Enterprise Applications 2012 EE\plugins\qad.plugin.reportserver\config ).
Make a copy of the example XML service configuration file for editing:
copy QadReportingFrameworkServiceConfig.example.xml to QadReportingFrameworkServiceConfig.xml.
Edit QadReportingFrameworkServiceConfig.xml in a text editor (such as Notepad). It has two main sections: one to configure the broker, and one to configure one or more agents that the broker manages. Each agent is a process that actually renders reports; it is recommended to have at least two agents for good throughput. An example of a two-agent configuration file is shown below:
 
<QadReportingFrameworkServiceConfig>
<Broker>
<Channel>qad.reporting.framework.service</Channel>
<Log.File>QadReportingFrameworkService.log</Log.File>
<Log.Level>INFO</Log.Level>
</Broker>
<Agents>
<Agent>
<Name>QADSVC-1</Name>
<StartupParameters>
<Config-Name>configuration_name</Config-Name>
<User>user_id</User>
<Password>(blank)</Password>
<Workspace>USA.USACO</Workspace>
<Enable>qad.plugin.financials</Enable>
</StartupParameters>
</Agent>
<Agent>
<Name>QADSVC-2</Name>
<StartupParameters>
<Config-Name>configuration_name</Config-Name>
<User>user_id</User>
<Password>(blank)</Password>
<Workspace>USA.USACO</Workspace>
<Enable>qad.plugin.financials</Enable>
</StartupParameters>
</Agent>
</Agents>
</QadReportingFrameworkServiceConfig>
The file entries should be edited as follows:
All of the <Broker> settings can be the same default values as in the above example.
The <Agent> <Name> values can be the same as in the above.
The <Agent> <StartupParameters> must be modified to point to the QAD .NET UI server system. The details are as follows:
<Config-Name> is the name of the desired configuration to connect to (same as the drop-down list at the bottom of the QAD .NET UI login screen).
<User> is the QAD .NET UI user ID for the service to connect as.
<Password> is the QAD .NET UI password for the service to connect with (if null, use (blank), as in the above example).
<Workspace> is the workspace key (Domain.Entity).
The line containing <Enable>qad.plugin.financials</Enable> must be present for Enterprise Edition (EE) systems, and must be deleted for Standard Edition (SE) systems.
4
Start the service:
Open the Windows Service manager program
(choose Control Panel|Administrative Tools|Computer Management, and then choose Services And Applications|Services from the left pane).
A list of Windows Services is displayed on the right pane. Locate the service called QAD Reporting Framework Service, right-click on it, and select Properties.
When the Properties form appears, select the Log On tab and select the option for logging on as This Account. Enter the account username (for instance, QAD\username) and password. Click OK to save the changes; the Properties form closes.
Right-click on the QAD Reporting Framework Service line and select Start to start the service. It should become fully operational for report processing within about 20 seconds. Similarly, you can later select Stop or Pause to stop or pause the service.
5
Inspect the log files for proper startup. The log files are located in the qad.plugin.reportserver subdirectory called logs (typically in a location such as C:\Program Files\QAD\QAD Enterprise Applications 2012 EE\plugins\qad.plugin.reportserver\logs).
Open the broker log file (QadReportingFrameworkService.log) and check for errors.
Open the agent log files (for instance, QADSVC-1.log, QADSVC-2.log) to see if any agent errors have occurred. These look like standard QAD .NET UI log files.
Check service status details:
From a DOS window, cd to the qad.plugin.reportserver plug-in directory (under the QAD .NET UI client installation plug-ins directory; typically in a location such as C:\Program Files\QAD\QAD Enterprise Applications 2012 EE\plugins\qad.plugin.reportserver)
Run QadRFSAdmin.exe Status and you will see a status report similar to that shown below. If the broker and agent statuses are all running, then the system is responding as expected. If one or more agents have a status of not responding in the log file, it could mean a problem has occurred. Try checking the status again a few seconds later. If it is still not correct, double-check the log files.
>QadRFSAdmin.exe Status
Broker Status:
Broker Status : RUNNING
Process ID : 1848
IPC Channel : qad.reporting.framework.service
Config File : C:\Program Files\QAD\QAD Enterprise Applications 2012 EE\plugins\ReportFramework\Build\Debug\plugins\qad.plugin.reportserver\config\QadReportingFrameworkServiceConfig.xml
Log File : C:\Program Files\QAD\QAD Enterprise Applications 2012 EE\plugins\ReportFramework\Build\Debug\plugins\qad.plugin.reportserver\logs\QadReportingFrameworkService.log
Log Level : DEBUG
Agents (2):
Agent Status : RUNNING
Agent Process ID : 2952
Agent IPC Channel : qad.reporting.framework.service.QADSVC-1
Agent Start Time : 10/25/2011 1:06:04 PM
Agent Memory Info : 48066 K (Mem Usage), 42573 K (VM Size)
Agent Last Report Action: Started listening at 2011-10-25 13:06:04
Agent Pending Request : PENDING_REQUEST_NONE
Agent Command Line : C:\Program Files\QAD\QAD Enterprise Applications 2012 EE\plugins\ReportFramework\Build\Debug\container\QAD.Client.exe -param.url:file:///C:/Program Files/QAD/QAD Enterprise Applications 2012 EE/plugins/qad.plugin.reportserver/config/QADSVC-1.pf
Agent Status : RUNNING
Agent Process ID : 5096
Agent IPC Channel : qad.reporting.framework.service.QADSVC-2
Agent Start Time : 10/25/2011 1:06:06 PM
Agent Memory Info : 50003 K (Mem Usage), 42471 K (VM Size)
Agent Last Report Action: Started listening at 2011-10-25 13:06:06
Agent Pending Request : PENDING_REQUEST_NONE
Agent Command Line : C:\dev-trunk\plugins\ReportFramework\Build\Debug\container\QAD.Client.exe -param.url:file:///C:/Program Files/QAD/QAD Enterprise Applications 2012 EE/plugins/qad.plugin.reportserver/config/QADSVC-2.pf
6
Test the service by scheduling a report to be processed by the service.
Log on to the QAD .NET UI system.
Open any report in the system that uses the QAD Reporting Framework. If none are on the menu, open Report Resource Designer, open any report, and then click the Preview button to run it from the designer.
Click the Schedule|New tool button to schedule the report:
Enter any Description.
Enter a blank Batch ID (this defaults to the virtual service batch QADSVC).
Leave Printer blank for basic testing purposes. If printer testing is desired, reporting printers must be defined in the QAD .NET UI home server configuration file (client-session.xml) before they appear on this form.
Check the Save Report Output option to have the scheduled report output saved on the web server.
Run Only Once can be selected or not since it is ignored (all service-mode servers run the reports only once regardless of this setting).
An Email address can be specified, but e-mailing will only succeed if SMTP has been set up on the .NET UI home server configuration file (client-session.xml).
Click the Schedule|View Schedule tool button to check the report’s status in the batch (it will exist in the batch queue until it has been run successfully).
Click the Schedule|View History tool button to check the report run results (which will not exist until the report has finished being run). Right-click on the URL column and select Scheduled Report Result to drill down to the output file, which is displayed in the QAD .NET UI below the history browse grid.
Administering the Reporting Framework Service
Routine administration of the service can be done using the standard Windows Service Manager tool, which allows functions such as start, stop, pause, and resume. It also allows the service to be automatically started at machine startup and other options.
There is also a QAD administrative utility that provides finer control over the service. It is a command line program called QadRFSAdmin.exe that is typically run from a DOS command prompt. It is located in the report server plug-in folder under the QAD .NET UI client installation folder. For example:
C:\Program Files\QAD\QAD Enterprise Applications\plugins\
qad.plugin.reportserver
To run the command line administration program, open a DOS command window, cd to the above folder, and then run QadRFSAdmin.exe.
The usage is as follows:

QadRFSAdmin [-f <config file>] <command> [param]
Valid commands:
QadRFSAdmin StartBroker
QadRFSAdmin StopBroker
QadRFSAdmin StartAgents
QadRFSAdmin StopAgents
QadRFSAdmin PauseAgents
QadRFSAdmin ResumeAgents
QadRFSAdmin StartAgent <agentChannelName>
QadRFSAdmin StopAgent <agentChannelName>
QadRFSAdmin KillAgent <agentChannelName>
QadRFSAdmin PauseAgent <agentChannelName>
QadRFSAdmin ResumeAgent <agentChannelName>
QadRFSAdmin CancelReport <agentChannelName>
QadRFSAdmin Status
The QadRFSAdmin program connects to the service broker using the same XML service configuration file as the service itself. If the service was configured using a non-default configuration file name or path, then the -f option can be used to point the QadRFSAdmin program to that file.
Note: If the Service was started under the Local System account instead of under a specific user account, then the QadRFSAdmin program will not be able to connect to the broker due to an IPC security restriction, giving an error message like this
> QadRFSAdmin status
Broker Status:
Error: Failed to connect to an IPC Port: Access is denied.
To resolve this issue, go to the Windows Services Manager program, select the QAD Reporting Framework service's Properties, go to the Log On tab, and select “This Account” and enter a Windows username and password for the account to run the service under, which must have administrative rights.
The QadRFSAdmin program provides a number of administrative commands as shown in the above usage output. The commands that affect a specific agent require an additional parameter specifying the agent’s channel name. This channel name is defined as the broker’s channel name with the agent name appended at the end after a dot (.). All of these channel names can be clearly seen in the output of the QadRFSAdmin Status command. For example:
 
>QadRFSAdmin.exe Status
Broker Status:
Broker Status : RUNNING
Process ID : 1848
IPC Channel : qad.reporting.framework.service
Config File : C:\Program Files\QAD\QAD Enterprise Applications 2012 EE\plugins\ReportFramework\Build\Debug\plugins\qad.plugin.reportserver\config\QadReportingFrameworkServiceConfig.xml
Log File : C:\Program Files\QAD\QAD Enterprise Applications 2012 EE\plugins\ReportFramework\Build\Debug\plugins\qad.plugin.reportserver\logs\QadReportingFrameworkService.log
Log Level : DEBUG
Agents (2):
Agent Status : RUNNING
Agent Process ID : 2952
Agent IPC Channel : qad.reporting.framework.service.QADSVC-1
Agent Start Time : 10/25/2011 1:06:04 PM
Agent Memory Info : 48066 K (Mem Usage), 42573 K (VM Size)
Agent Last Report Action: Started listening at 2011-10-25 13:06:04
Agent Pending Request : PENDING_REQUEST_NONE
Agent Command Line : C:\Program Files\QAD\QAD Enterprise Applications 2012 EE\plugins\ReportFramework\Build\Debug\container\QAD.Client.exe -param.url:file:///C:/Program Files/QAD/QAD Enterprise Applications 2012 EE/plugins/qad.plugin.reportserver/config/QADSVC-1.pf
Agent Status : RUNNING
Agent Process ID : 5096
Agent IPC Channel : qad.reporting.framework.service.QADSVC-2
Agent Start Time : 10/25/2011 1:06:06 PM
Agent Memory Info : 50003 K (Mem Usage), 42471 K (VM Size)
Agent Last Report Action: Started listening at 2011-10-25 13:06:06
Agent Pending Request : PENDING_REQUEST_NONE
Agent Command Line : C:\dev-trunk\plugins\ReportFramework\Build\Debug\container\QAD.Client.exe -param.url:file:///C:/Program Files/QAD/QAD Enterprise Applications 2012 EE/plugins/qad.plugin.reportserver/config/QADSVC-2.pf
In the above example, the channel name for the first agent is: qad.reporting.framework.service.QADSVC-1
The QadRFSAdmin commands are described below:
QadRFSAdmin StartBroker — Starts a Reporting Framework Service broker process, which in turn spawns agent processes. This is essentially the same thing that occurs if the service is started using the Windows Service Manager, except that the Windows service layer is bypassed. It is generally advisable to use the Windows Service Manager instead of this command line function.
Note: This command should not be run if the service has already been started using the Windows Service Manager.
Note: After this command is run, the DOS command window is unusable until the service is stopped. The DOS window should not be closed until the service has been stopped using the StopBroker command; otherwise the agent processes remains running and orphaned. Should this occur, however, the agent processes (QAD.Client.exe) can be manually killed using Windows Task Manager.
QadRFSAdmin StopBroker — Stops a Reporting Framework Service broker process, which in turn gracefully terminates its agent processes. This is essentially the same thing that occurs if the service is stopped using the Windows Service Manager, except that the Windows service layer is bypassed. It is generally advisable to use the Windows Service Manager instead of this command line function.
Note: This command should not be run if the service was started using the Windows Service Manager.
QadRFSAdmin StartAgents — Starts a new pool of service agents. Has no effect if the agent pool has already been started.
QadRFSAdmin StopAgents — Stops and gracefully terminates each agent in the pool. The broker process is still kept alive.
QadRFSAdmin PauseAgents — Pauses each agent in the pool. Each agent process remains alive but report processing is suspended. Only has effect if the agents are running.
QadRFSAdmin ResumeAgents — Resumes each agent in the pool. Only has effect if the agents are paused.
QadRFSAdmin StartAgent <agentChannelName> — Starts the specified agent process. Only has effect if that agent process is not already running.
QadRFSAdmin StopAgent <agentChannelName> — Stops and gracefully terminates the specified agent process. If the agent is currently running a report, it is not stopped until that report finishes.
QadRFSAdmin KillAgent <agentChannelName> — Similar to StopAgent, except that if the graceful termination does not succeed after a few seconds (for instance, if the agent is processing a long-running report or is frozen for some reason), then an ungraceful process kill is initiated to force termination of the agent.
Note: If a kill is being attempted to stop an agent that is running a long report query, the CancelReport command should be issued first to cancel the server resources being used for the query. In many such cases, the CancelReport command will suffice to restore the agent back to proper running order.
QadRFSAdmin PauseAgent <agentChannelName> — Pauses the specified agent in the pool. The agent process remains alive but report processing is suspended. Only has effect if the agent is running.
QadRFSAdmin ResumeAgent <agentChannelName> — Resumes the specified agent in the pool. Only has effect if the agent is paused.
QadRFSAdmin CancelReport <agentChannelName> — Instructs the specified agent to cancel the report it is currently running. Only has effect if the agent is running the report.
Note: This command is an essential tool for use in situations where a report run results in a long-running query that must be terminated to restore server performance. The cancelation should free up database and application server query resources after a few seconds.
QadRFSAdmin Status — Provides a detailed description of the current state of the QAD Reporting Framework Service, including the status of the broker and each agent. An example of its output is show above.
Note: If the Windows Service Manager is being used to start the QAD Reporting Framework Service, then the StartBroker and StopBroker commands should not be used. However, all of the other commands are OK to use in this case.