ReportCaster Processing

In this section:

Reference:

The following image shows the ReportCaster components and the processing that takes place when ReportCaster accesses an SQL repository to create, execute, and distribute a scheduled job.

The ReportCaster Distribution Server and its relationship to the Application SErver, the Reporting Server, and other program components as it generates scheduled report output.

The Distribution Server is a Java application that governs the process of submitting and distributing a scheduled job. You can install the Distribution Server on the same platform as the TIBCO WebFOCUS® Reporting Server and the components (which reside on the web or application server), or it can be installed on a different platform.

The WebFOCUS® Reporting Server processes a scheduled request, retrieves the data, and returns the report to the Distribution Server, which distributes the output. ReportCaster supports multiple Reporting Servers (specified in the ReportCaster Configuration tool), and one Repository (specified in the Application Settings folder within the Repository).

When you create a ReportCaster schedule, one of the properties of the schedule set by ReportCaster is the next run time (NEXTRUNTIME) for that schedule. The Distribution Server checks for schedules in the Repository that have a next run time less than or equal to the current time. Once the scheduled job runs, the NEXTRUNTIME is updated to the next instance that the schedule is set to run.

Reference: ReportCaster Processing of a Scheduled Job

The following steps describe what happens when the Distribution Server identifies a schedule to run.

  1. The Distribution Server prioritizes the scheduled job with other schedules in the Distribution Server queue. When creating a schedule, there is a Priority parameter where you can specify a priority value from 1 to 5, where 1 is the highest priority and 5 is the lowest priority. The default priority value is 3. The Distribution Server queue sorts scheduled jobs by priority and then by time. If during a schedule cycle one or more jobs remain in the queue when the next schedule cycle begins, these jobs are reprioritized to include new jobs entering the queue.
  2. When a session (thread) to the Reporting Server is available, the Distribution Server dynamically retrieves schedule, parameter, and alert information from the WebFOCUS Repository. The number of concurrent threads available for job dispatching is controlled by the Maximum Thread parameter setting in the ReportCaster Console Configuration tool. Each Reporting Server that is configured in ReportCaster has its own thread allocation. In addition, threads can be allocated for jobs that do not use a Reporting Server. The maximum number of threads is the total of these separate thread settings. Additionally, reports (WebFOCUS Reporting Server Procedures, Standard Reports, and My Reports) are packaged for submission to the IBFS system for security and WF Client configuration processing. The IBFS system submits the scheduled job to the Reporting Server.
  3. When the scheduled job is a:
    • Procedure (WebFOCUS Server Procedure or Managed Reporting procedure). The retrieved reports are packaged for submission to a Reporting Server. When ReportCaster prepares and submits a scheduled job for WebFOCUS Server Procedures or WebFOCUS reports (Managed Reporting), it sends commands to the IBFS system to submit to the Reporting Server. Resource Analyzer, which is used to track and monitor requests submitted to the Reporting Server and resources used to create the report that will be distributed, then retrieves these commands for the purpose of monitoring the resources used to create the report. The Reporting Server runs the procedure, retrieves the data, creates the report, and returns the report to the IBFS system which returns it to the Distribution Server. The Distribution Server then processes the distribution information and distributes the report. For graph requests, the data is returned to the Distribution Server, which creates the graph image and distributes it.

      Note: You can specify that certain commands are to be run prior to the execution of a scheduled job by using the Universal Profile setting in the WebFOCUS Administration Console.

    • URL. The Distribution Server submits the URL to a web server, which runs the URL. The content is then sent back to the Distribution Server, which distributes it.
    • File. The Distribution Server accesses its mapped drives to retrieve the file, which it then distributes.
    • FTP. The Distribution Server accesses an FTP server and retrieves the report output, which it then distributes.
    • WebFOCUS Schedule. Based on the option the user has selected, the Distribution Server either runs the called schedule immediately before any other queued jobs, or adds the called schedule to the queue in respect to its priority.
  4. The Distribution Server distributes scheduled output as an email message, through FTP or SFTP, to a printer, as a report in a Managed Reporting (WebFOCUS Repository) folder, or to the Report Library. You can also distribute the scheduled output to a fax machine using a third-party email to fax provider.

    WebFOCUS Server Procedures and Managed Reporting support bursting, which enables you to send portions of a report to specific recipients. If you are distributing a burst tabular report, the burst value is determined by the first BY field. If you are distributing a burst graph report, the burst value is determined by the second BY field. The burst value is automatically determined by the internal matrix. The internal matrix is a memory area that stores each database field value and calculates values referenced by the TABLE or GRAPH request.

  5. When the Distribution Server has distributed the output (or is unable to distribute the output), it then processes the log information and writes job information to the log tables in the WebFOCUS Repository.

    Note: The logging process has been modified so that messages are written to the WebFOCUS Repository as they are available, rather than all at once at the end of a schedule. ReportCaster log information is written to the log tables as the schedule progresses. As a result, you can run a log report while a schedule is running to determine how far a schedule has progressed.

    Error conditions in log reports appear in red text and warnings appear in orange text.

  6. If notification is requested, the Distribution Server sends an email notification. The name of the mail server that processes the notification email is specified in the Notify Mailhost setting in the Configuration tool. If mail server is blank, ReportCaster uses the default mail server used to distribute an email schedule, which is specified by the Mailhost setting in the Configuration tool.

    Error conditions occur for log reports or notification when:

    • A FOC error message is returned to the Distribution Server.
    • There is no report to distribute.
    • There was an error when communicating to services (Email, FTP, SFTP, printer, Managed Reporting, Repository, Report Library).

    Tip: We recommend using different mail servers for notification and email distribution. Using separate mail servers ensures that you will still receive notifications if the default mail server falters.

Example: Executing a Scheduled Job

In this example, the Distribution Server polls the BOTSCHED table every minute looking for scheduled jobs. However, note that ReportCaster enables authorized users to change the polling interval for the Distribution Server using the Reader Interval setting in the Configuration tool. You can specify an interval from 1 to 999999 minutes.

  1. At 9:01 AM, you schedule a job with a start date/start time of today at 12:00 PM and an end date/end time of tomorrow at 3:00 PM. The job is scheduled to run every two hours.
  2. At 9:02 AM, the Distribution Server reads all records from the BOTSCHED table with a NEXTRUNTIME equal to the current time. The job does not qualify since it has a start time of 12:00 PM.
  3. The Distribution Server polls the BOTSCHED table every minute thereafter, looking for jobs with a NEXTRUNTIME less than or equal to the current time.
  4. At 12:00 PM, the Distribution Server reads the BOTSCHED table. The job qualifies since its NEXTRUNTIME is equal to the current time. The job is put in the Distribution Server queue and the Distribution Server updates its NEXTRUNTIME by two hours so that the NEXTRUNTIME is 2:00 PM.
  5. The Distribution Server polls the BOTSCHED table every minute thereafter, looking for jobs with a NEXTRUNTIME less than or equal to the current time.
  6. At 2:00 PM, the Distribution Server reads the BOTSCHED table. The job qualifies since its NEXTRUNTIME is equal to the current time. The job is put in the Distribution Server queue and the Distribution Server updates its NEXTRUNTIME by two hours so that the NEXTRUNTIME is 4:00 PM.
  7. This process repeats itself. The job will run every two hours until 3:00 PM tomorrow. The last time the job will be put in the run queue is tomorrow at 2:00 PM.

Note: For additional schedule considerations, see Time Zone Considerations.

Time Zone Considerations

All times that are displayed in a job schedule are defined in terms of the time zones assigned to them. The time zone defined within a schedule enables the Distribution Server to run scheduled distributions at the appropriate local time, regardless of the time zone in which the Distribution Server is located.

During product installation, the time zone assigned to the operating system of the server on which WebFOCUS is installed is added to the ReportCaster configuration. This time zone appears in all new schedules, by default. However, if the recipients of scheduled distribution content are located outside of that time zone, schedule times must be adjusted to ensure that scheduled content arrives at the appropriate time. In order to make this adjustment, we recommend that you replace the default time zone with the time zone of the recipients of your content.

By selecting a time zone, you can easily schedule a distribution for a local time that is most convenient to the recipients of the distributed content, without having to factor the time difference into the values you assign to the times in the schedule. For example, if you are working in New York with a default time zone of EST and want to start the distribution of content at 9:00 AM in London, you only need to select the (UTC) Dublin, Edinburgh, Lisbon, London time zone entry and set the Start Time to 9:00 AM. Without this ability, you would be required to calculate the equivalent time in New York, 4:00 AM, and use that value as the Start Time.

Time zones are identified in terms of their offset from Coordinated Universal Time (UTC). These offsets identify the number of hours that a local time zone is ahead of or behind the time zone located at zero degrees longitude. Time zone entries are also identified by time zone name or by cities within the zone. For example, (UTC – 5:00) is identified in one entry as Eastern Time (US & Canada) and in another entry by the South American cities that fall within it, Bogota, Lima, and Quito. Because both entries use the same offset, the same number of hours is used for both entries when converting time values.

ReportCaster uses Java technology, which always adjusts for Daylight Saving Time, regardless of Windows® settings. If you are in an area that does not observe Daylight Saving Time, scheduled jobs will run at the correct time. However, some internal files will add an hour to time stamps during this period. These files include the following:

Daylight Saving Time Considerations

When considering the effect of Daylight Saving Time (DST) for jobs scheduled by ReportCaster, the main thing to remember is that 1:59:59 AM is when the time change occurs. As a result, the clock time is set to either 3 AM (when DST begins) or 1 AM (when DST ends).

A simple rule to remember is that regardless of the time change, the schedule interval stays the same. This is because the schedule run time is based on elapsed time rather than the actual clock time.

The following table lists and describes the expected behavior for jobs scheduled by ReportCaster when Daylight Saving Time is in effect.

Interval

Description

For example:

Schedule is set to run once at a specific time, or to run every day, week, month, or year.

The schedule runs at that time, regardless of the time change.

A 9:15 AM schedule will still run at 9:15 AM.

Schedule is set to run every minute or hour when DST begins.

The schedule is advanced by 1 hour.

A schedule that runs every 2 hours: 12:00 AM, 2:00 AM, 4:00 AM, and so on.

Will run at the following times: 12:00 AM, 3:00 AM, 5:00 AM, and so on.

This occurs because at 1:59:59 AM, the clock is set ahead to 3:00 AM.

Schedule is set to run every minute or hour when DST ends.

The schedule is set back 1 hour.

A schedule that runs every 2 hours: 12:00 AM, 2:00 AM, 4:00 AM, and so on.

Will run at the following times: 12:00 AM, 1:00 AM, 3:00 AM, and so on.

This occurs because at 1:59:59 AM, the clock is set back to 1:00 AM.

Establishing a Location for the ReportCaster temp Directory

How to:

The ReportCaster temp directory is a staging area for reports. The location of the temp directory is not configurable using the ReportCaster tools. However, you can issue commands to point to a different location, if the default location does not provide enough space to stage your reports.

Procedure: How to Point to a Location for the ReportCaster temp Directory

In these directions, the new location of the temp directory will be on a drive named D on Windows, or a new directory on Unix/Linux.

  1. Create a new path for the new temp directory.

    On Windows, the new path can be:

    D:\ReportCaster\temp

    On UNIX or Linux, the new path will be referred to as:

    path_to_newdir/ReportCaster/temp

    The DOS commands for creating this directory are:

    D:
mkdir ReportCaster\temp

    The UNIX or Linux commands for creating this directory are:

    cd path_to_newdir
mkdir /ReportCaster/temp
  2. Delete the original ReportCaster temp directory.

    On Windows, the default original location is:

    C:\ibi\WebFOCUS82\ReportCaster\temp

    On UNIX or Linux, the default original location is:

    /home/user/ibi/WebFOCUS82/ReportCaster/temp

    The DOS commands for removing this are:

    cd C: \ibi\WebFOCUS82\ReportCaster
rmdir temp /s /q

    The UNIX or Linux commands for removing this are:

    cd /home/user/ibi/WebFOCUS82/ReportCaster
rm -r temp
  3. Create a virtual directory called temp in its place, pointing to the new directory on the D drive:

    The DOS command for creating this link is:

    mklink /D C:\ibi\WebFOCUS82\ReportCaster\temp D:\ReportCaster\temp

    The UNIX or Linux command for creating this link is:

    ln -s path_to_newdir/ReportCaster/temp /home/user/ibi/WebFOCUS82/ReportCaster/temp

    This will create the configuration change needed.