4 Submitting Batch Jobs and Reports

Many Oracle Clinical functions are executed by batch jobs submitted to Oracle servers (Reports Server, Web Server) or third-party applications (SAS). Batch jobs are non-interactive programs, such as reports and procedures, that run in the background. That is, the program runs in a separate process and does not interfere with your task. For example, the program that performs data validation runs without input from you, and without showing any output on your screen.

The Oracle Reports Server handles reports and scheduled jobs, while the Oracle Clinical Parameterized job and report SUBmission facility (PSUB) handles procedures written in PL/SQL. You need to be aware of which kind of job you are running.

This chapter contains the following information:

Overview of the Submission Process

represents the forms you use to submit and manage batch jobs, and the workflow among them. The callout numbers describe the most basic sequence of steps required to run a batch job:

  1. Menu item or button. You select an Oracle Clinical task, from a menu or toolbar.

    The Submission of Module window appears, showing the parameters required for execution of the selected job.

  2. Submission of module. You enter values for all the mandatory parameters.

  3. Choose Action, then Batch Jobs to see the status of the Oracle Clinical jobs that you started.

    The Submitted Batch Jobs window displays the status of your Oracle Clinical jobs.

  4. Upon completion. If your Oracle Clinical job finishes successfully, you can view the results on the screen and you can also print the results.

    If your Oracle Clinical task does not succeed, you can view the log file, or contact your system administrator to determine and fix the problem.

Entering Parameters for a Job

When you select a task that requires a batch job, the Submission of Module window appears and displays a list of the parameters needed, as shown in . The list may include a few of the fields that show on the final report or process. It may also include some fields that are not part of the final process but that limit the number of records in the report, or that are required in order to execute the job.

Figure 4-1 Submission of Module Window

Description of Figure 4-1 follows
Description of ''Figure 4-1 Submission of Module Window ''

The label at the top center shows your current task. The label below the task name indicates whether the job is a Report or a PSUB job (some tasks that generate reports are run by PSUB, not the Oracle Reports server). If it is a Report, you can now choose which server computer you want to run it, and, if the output type is PRINTER, which printer you want.

The parameters in the Description column are displayed with their default values, if any. Three check boxes indicate the options for setting these parameter values:

Table 4-1 Check boxes in the PSUB Window

Check box Effect

Mandatory?

If checked, the parameter must have a value. If there is no default value supplied, you must enter one.

LOV?

If checked, a List of Values is available for you to choose from.

Pattern?

If checked, you can use a wildcard search to limit the number of records reported.

When you enter a value for a parameter in the Current Value field, Oracle Clinical validates the value to ensure that it meets any requirements established for the parameter. You receive a message if the value you entered fails validation.

Submitting the Batch Job

After defining the submission parameters and submission details such as execution mode, follow these steps to send the job for processing:

  1. Start at the Submission of Module window.

    • If you are using a saved parameter set without changing the execution definitions, you are already at this window.

    • Return to the block after making changes in the Submission Details window.

      Note:

      If Mode of Execution is set to batch_scheduled, you must save the parameter set before submitting the job. See "Saving a Parameter Set" for instructions.

  2. Click the Submit Job button to submit the batch job.

  3. A message states that the transaction is complete and that the batch has been submitted. You also receive a message telling you what the output file is, if any.

  4. To view the status of your submitted job, select the Job Status button from the navigation bar. See "Status of Submitted Jobs" for details.

Note:

You can request only one batch job at a time. However, several jobs can run at the same time. To request more batch jobs, you must repeat this procedure.

Modifying Job Details

Once you have entered the parameters for the job, you can view the details of how the job is to be submitted by clicking the Job Details button. The fields in the Submission Details for Task window have default values set by your system administrator. They should be sufficient to run the job as set, but can be modified.

The Submission Details for Task window allows you to specify the output form of the results of a batch job: print, computer display (screen), or file, and where and when you want it to be printed or saved.

Figure 4-2 Submission Details for Task Window

Description of Figure 4-2 follows
Description of ''Figure 4-2 Submission Details for Task Window''

Follow these steps to modify fields in the Submission Details for Task window:

  1. Fill in the fields for Mode of Execution, and server or printer.

    Note:

    If Mode of Execution is set to batch_scheduled, you must save the parameter set before submitting the job. See "Saving a Parameter Set".

  2. Make sure that all other parameters are set to your satisfaction. Contact your system administrator for more information on batch and print queue names.

  3. Click Submit Job to start the job and return to the Submission of Module window.

Table 4-2 Fields in the Submission Details for Task Window

Name Description

Mode of Execution

The type of scheduling needed to run this batch job:

BATCH_SCHEDULED = run repeatedly at a specified day and time.

BATCH_IMMEDIATE = run in batch mode as soon as possible.

PSUB Queue
Report Server

For PSUB jobs, the name given to the batch queue.
For Reports, the server computer that runs Oracle Reports.

Output Type

Device to handle the result of the batch job. One of:

SCREEN = displayed on a monitor.

FILE = saved in a file; not displayed on a monitor or printed.

PRINTER = sent directly to a printer.

PREVIEW = displayed in Reports Pre-viewer on your screen. You can then choose whether to print it.

Output Format

Kind of file to contain the result of the batch job. One of:

TEXT = Plain ASCII characters. Prints anywhere.

POSTSCRIPT = Adobe PostScript print format. Printer must have PostScript driver installed.

PDF = Adobe Portable Document Format. For viewing only.

RTF = Rich Text Format. Compatible with Microsoft Word.

HTML = HyperText Markup Language. For Web viewing

Printer

Name of the printer to which the batch job is sent.

Default: defined by system administrator for system default, by reference codelist OCL_JOB_PREF for the database.

Keep File

Whether to retain the output after the job is run.

Default: ON (checked)

Output Filename

Name of the output file generated by the batch job.

Enabled only if Keep File checked.

Reports Queue Manager

The Reports Queue Manager enables you to see scheduled and past jobs on the selected Reports Server, and to stop or reschedule a batch job. You can only examine one Reports Server's queue at a time, using this application.

To launch the Reports Queue Manager for a particular Reports Server:

  1. Choose Admin, then PSUB/Report Jobs, and Report Queue Manager. The Report Queue Manager window opens.

  2. Choose the Reports Server that you want to examine from the LOV. The window populates with its full domain and server name in the right most fields.

  3. Click OK. Oracle Clinical opens a new browser window, which loads the Reports Queue Manager data.

Each row represents a single batch job. Click the hyperlinked job status to investigate a particular job and manipulate it.

Scheduling Jobs that Repeat

Click the Schedule button in either the Submission of Module or the Submission Details window to schedule a job, either repeating or not (called "batch deferred" in previous versions).

Figure 4-3 Schedule Jobs Window

Description of Figure 4-3 follows
Description of ''Figure 4-3 Schedule Jobs Window''

Table 4-3 Fields in the Schedule Jobs Window

Name Description

Report Server/Scheduler
or
Schedule Queue

Reports Server that processes reports jobs
or
Reports Server that schedules PSUB jobs.

Display only. Value set in Submission Details for Task window.

Start

Use these fields to set the time and day.

Immediately option

As soon as your request gets to the server. Use this option only if the scheduled job starts on today. You must enter the first date the job runs in the At option, if it is not today.

At option, time field

Time of day in format HH:MI AM or PM, that is, a twelve-hour clock.

On option, date field

The date of the first run of the job. Day of the year in your local format (default is dd-mon-year).

Repeat

Use these fields to set the interval between repeats (if any).

Do not repeat option

Run the job just once.

Every option, number and units fields

A positive integer and a unit of time.

Default is 1 Hour. shows every day.

Every option, ordinal and day fields

An ordinal number and a day of the week.

Default is first Monday of the month.

Last option, day and date fields

A day of the week and a date of the month.

Default is last Monday on or before the 31st of the month.

Status of Submitted Jobs

After you submit the job, you can view its status in the Submitted Batch Jobs window by selecting the Job Status button in the Submission of Module window. You can also reach the window by choosing Action, and thenBatch Jobs from any Oracle Clinical window or by choosing Admin, then PSUB/Report Jobs, and Batch Jobs from the main navigator tree. You cannot update fields in the Submitted Batch Jobs window.

This section includes the following tasks:

Viewing Job Status

In this window you can view various aspects of your job, such as its current execution status, log and output file names, failure text if the job failed, as well as various timestamps. The execution status of each job changes as the job moves from entered, to started, and then to success.

If you are viewing this form while the job is executing, click Auto Refresh button on the navigation bar to have Oracle Clinical automatically update the status display. A second click turns off the auto refresh.

Understanding Log and Output File Names

The names of the files are structured as follows: the unique batch job ID for the job is prefixed with an L for the log file, and with an O for the output file; for example, a batch job with a batch job ID of 12345 would have an output file name of RXC_LOG:O12345.OUT, and a log file name of RXC_LOG:L12345.LOG.

If you want to print the output or log file, click the Print Output or Print Log button on the navigation bar. If you want to see the files onscreen without printing them, you click View Output or View Log. If there are multiple files, a dialog box appears and you can select the one you want. For convenience, the output file is included in the log file dialogs.

  • PSUB job: As of Release 5.0, log and output files are saved only temporarily to a file system directory, then are immediately uploaded to the database where the View and Print buttons access them. The temporary directory is specified in the PSUB_LOGS_DIR value of the OCL_STATE reference codelist.

    The PSUB_LOGS_DIR value is fetched from the ocl_state ref codelist. A Username-specific directory is created on the database server when a user submits a PSUB job for the first time and is used for all subsequent jobs submitted by that particular user. The Job ID is specific to every job run.

  • Report job: Log and output files are placed in the Report Server Directory on the server that is defined in the Oracle Accounts of Oracle Clinical. (Navigate to Admin, then Users, then Oracle Accounts.)

Table 4-4 Fields in the Submitted Batch Jobs Window

Name Description

Job Id

Unique system-generated ID for the batch job submission

Module Name

Name of the module that is being executed

Execution Status

Status of the batch job

ENTERED = You have requested submission of the job.

SUBMITTED = Job has been submitted to the batch queue.

SUBMIT_TO_RS = Job has been submitted to the server queue

SUBMIT_FAILED = Job failed submission to the batch queue.

STARTED = Job is currently executing.

SUCCESS = Job has completed successfully.

FAILURE = Job has completed unsuccessfully.

STOPPED = Job has been stopped by the Stop button.

STOP_FAILED = Job has not responded to the Stopbutton.

Study

Name of the study.

Parameter Set Name

Parameter Set Name that was loaded for this job.

Temporary Output Loc

Name of the directory where the output file was generated before being written to the database table BATCH_JOB_LOBS.

Failure Text

Text the job generates to give information about why it failed

Temporary Log Loc

Name of the directory where the log file was generated before being written to the database table BATCH_JOB_LOBS.

Mode of Execution

Type of scheduling that ran this job

BATCH_IMMEDIATE = run in batch mode as soon as possible

BATCH_SCHEDULED = run repetitively at a specified day and time

Module Type

Type of module executed in batch: REPORT, 3GL, DCL, PLSQL

Server Queue

Name of the server queue to which you sent the job

Print Queue

Name of the print queue to which you sent the job

Job Request Time

Date and time you clicked the Submit Job button

Job Submission Time

Date and time the job was actually submitted

Scheduled Time

Date and Time the job was scheduled.

Job Start Time

Date and time the job started

Job Completion Time

Date and time the job completed

Format

File format of the output file: ASCII, PDF, or POSTSCRIPT

Report ID/Process ID

The internal identification of the processed report (processed on the Report Server) or PSUB Job (processed on the PSUB Server).

Job Name

Name of the job processed on the Report Server. It is shown on the Report Queue Manager as well.

RS Scheduler

Report Server computer that owns the server queue

Schedule String

Time that you specified for the job start time.

Command Line

Command Line sent to the server.

Stopping Jobs

You can stop a job, even if it is in a job set, by clicking the Stop button. A stopped job has a status of STOPPED; if the job doesn't respond to the action, its status is STOP_FAILED. You can stop only your own jobs. Oracle Clinical does not delete log and output files associated with PSUB jobs; the system deletes log files from reports jobs when you stop the job.

Using a Saved Parameter Set

Description of paramset.gif follows
Description of the illustration ''paramset.gif''

A parameter set is a saved grouping of one or more parameter values that you have specified in the Submission of Module window. If you know that you plan to execute the same batch job repeatedly, it may save you time to create a parameter set. Saving the parameter set also saves the associated execution definition. Once saved, a parameter set can be reused and/or modified.

Similarly, if you want to execute a series of batch jobs in a certain order, you can create a job set. Each job in a job set must have a saved parameter set. You cannot run job sets immediately; they execute only on a server.

Saving a Parameter Set

You must save a parameter set if the batch job mode of execution value is BATCH_SCHEDULED. Follow these steps:

  1. Create or modify parameters as explained in "Entering Parameters for a Job".

  2. Return to the Submission of Module window.

  3. Select Save Param Set from the Special menu. The Save Parameter Set Name window appears.

  4. Enter a unique name for this new or modified parameter set, and select [OK].

  5. The system displays a confirming message and displays the Submission of Module window.

  6. Select [Exit] to end the function and return to the menu.

Modifying a Saved Parameter Set

After you select and display a saved parameter set, you can modify it to meet your current needs and then save it, if appropriate, using a new name.

When you save a parameter set, you also save the batch job execution definition settings. These settings can then be used automatically, or changed. If you change the execution settings, the changes are lost unless you save them under a new name.

Follow this procedure to use your saved set of parameters to submit a job:

  1. Select the report or other batch job from the Main Menu. The Submission of Task window appears, showing the parameters for the batch job.

    To use the parameters currently displayed in the PSUB Submission window, go to Step 3.

  2. To use a saved parameter set, do the following:

    1. Select Load Param Set from the Special menu. The Load Parameter Set Name window appears.

    2. Enter the name of the saved parameter set you want in the Parameter Set Name field, or make a selection from the list of values.

    3. Click OK.

    4. The Submission of Module window appears, with the Current Value field filled in for each parameter. If you don't want to modify the saved parameter set, go to Step 3. If you want to modify the set, change the entries in the Current Value field.

  3. Do one of the following:

    • Click Submit Job if you want to submit a job using the currently displayed parameters. See "Submitting the Batch Job" for instructions.

    • Select Save Param Set from the Special menu if you want to save the modified parameter set.

    • Click Job Detailsto move to the Submission of Module Details window.

Controlling Execution Order Using Job Sets

You can control the order for a specified set of jobs when you want jobs that depend on other jobs to execute only if the jobs on which they depend have been successfully executed.

The first task is to define a job set, provided you have saved a parameter set for each of the jobs in the job set. Navigate to Admin, PSUB/Reports Jobs, then Job Sets and enter a name for the job set, which is restricted to alphabetic characters. List the various jobs in this set; the parameter set names previously saved are entered automatically or from a LOV. The Task Name field is typically the name of a report and is entered when the parameter set is entered.

For each job in the job set, enter the job label of a related job in the appropriate status column. The status column you choose indicates what status the job in the left-hand column should have before the related job should start. If you leave one of the fields blank and the job in the left-hand column ends with the corresponding status (for example, the job ends successfully and the field in the Success column is empty), the execution of the whole job set stops.

The Time-out field that refers to the job in the left-hand column has a default of 720 minutes. The Time-out field that refers to the related job indicates only whether the job is permitted to time out before or after another job executes.

If any of the jobs in a job set exits with a status of SUBMIT_FAILED or STOPPED, the whole job set aborts with a status of FAILURE.

Oracle Clinical limits you to a maximum of 52 saved records in a job set. If you run a sequence of more than 52 jobs, divide them into smaller sets.

You submit job sets following the menu path Admin, PSUB/Reports Jobs, then Submit Job Set and then providing a job set name, for which there is a list of values.

Log Files for Job Sets

Oracle Clinical stores log files for job set submissions in the Report Queue Manager, and does not produce output files. For more information about seeing these log files, see "Reports Queue Manager".

Desupported Reports

The following reports have been desupported. All reports still have links under Data Entry, Data Entry Reports.

  • Project Enrollment

  • Study Enrollment

  • Site Enrollment

  • Site Summary