4 Programming BI Scheduler VBScript and JScript Jobs

This chapter describes how you can use the Oracle BI Scheduler to schedule general purpose scripts that extend the functionality of Oracle Business Intelligence.

Scripts can either be standalone Script Jobs (in Job Manager), or Script Actions tagged onto the end of agents. (For more information on agents, see Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition). Both types of script use the same script facilities, with a few exceptions. For example Script Actions can access the result set that is being delivered by the agent, while standalone Script Jobs have no access to result sets.

Oracle BI Scheduler includes a Script object that encapsulates a running script.The Script object represents a script and exposes the properties and methods of a script. You can access its methods and properties directly because its name is implied. For example, to access the JobID property, you can specify JobID, not Script.JobID.

Note:

Scripting for agents and scripts defined by Oracle BI Scheduler Job Manager are supported only under Windows platforms and are not supported under UNIX.

This chapter describes how to configure custom script properties, includes scripting examples, and provides detailed information about script job properties. It contains the following topics:

4.1 Configuring Custom Script Properties for Oracle BI Scheduler

Use the following procedure to modify the properties of an existing Oracle BI Scheduler script.

To add this job as a standalone job in Job Manager, see Section 3.2, "Adding Oracle BI Scheduler Jobs in Job Manager."

Note:

The script has to exist on the Oracle BI Scheduler server computer before you can configure the properties.

To configure custom Oracle BI Scheduler script properties:

  1. Set the custom properties according to Section 6.4, "Job Action Properties Available in Job Manager."

    For example, for the purgeSASCache.js script, use the values that are shown in the following table. To view an example of the SASCache.js script, see Section 4.2, "Creating a Custom Script Example - Cache Clearance."

    Field Value or Setting

    Script Type

    JScript

    Script / Script File check boxes

    Script File

    Script

    purgeSASCache.js

    Parameter(0): User

    Administrator

    Parameter(1): Password

    your_password


  2. Click OK.

4.2 Creating a Custom Script Example - Cache Clearance

You can use the purgeSASCache.js script to periodically purge all of the cache from the Oracle BI Server. The file must be saved in the following directory:

ORACLE_INSTANCE\bifoundation\OracleBISchedulerComponent\coreapplication_obischn\scripts\common

/////////////////////////////////////////////////////////
//purgeSASCache.js
//
//Purges the cache on SAS.
//Parameter(0) - The user name to pass in to NQCMD.
//Parameter(1) - The password for the aforementioned user.
/////////////////////////////////////////////////////////
//The full path to nqcmd.exe
var nqCmd = "[$INSTALLDIR]\\server\\Bin\\nqcmd.exe";
//The data source name
var dsn = "BI Web";
//The user to execute the queries
var user = Parameter(0);
//The password of the aforementioned user
var pswd = Parameter(1);
//The ODBC procedure call for purging the cache
var sqlStatement = "{call SAPurgeAllCache()};";
//////////////////////////////////////////////////////////
//Returns a string from the file name
//////////////////////////////////////////////////////////
function GetOutput(fso, fileName)
{
    var outStream = fso.OpenTextFile(fileName, 1);
    var output = outStream.ReadAll();
    outStream.Close();
    return output;
}
//////////////////////////////////////////////////////////
// Get WshShell object and run nqCmd. Capture the output
// so that we can handle erroneous conditions.
var wshShell = new ActiveXObject("WScript.Shell");
// Create a temp file to input the SQL statement.
var fso = new ActiveXObject("Scripting.FileSystemObject");
var tempFolder = fso.GetSpecialFolder(2);
var tempInFileName = fso.GetTempName();
var tempOutFileName = fso.GetTempName();
tempInFileName = tempFolder + "\\" + tempInFileName;
tempOutFileName = tempFolder + "\\" + tempOutFileName;
var tempInFile = fso.CreateTextFile(tempInFileName, true);
tempInFile.WriteLine(sqlStatement);
tempInFile.Close();
try
{
    // execute
    var dosCmd = nqCmd + " -d \"" + dsn + "\" -u \"" + user
        + "\" -p \"" + pswd + "\" -s \"" + tempInFileName + "\"" +
        " -o \"" + tempOutFileName + "\"";
    wshShell.Run(dosCmd, 0, true);
    var output = GetOutput(fso, tempOutFileName);
    // Remove the temp files
    fso.DeleteFile(tempInFileName);
    if (fso.FileExists(tempOutFileName)) {
        fso.DeleteFile(tempOutFileName);
}
    // Check the output for any errors
    if (output.indexOf("Processed: 1 queries") == -1) {
        ExitCode = -1;
        throw Error(-1, output);
    }
    else if (output.indexOf("Encountered") != -1) {
        ExitCode = -2;
        throw Error(-2, output);
    }
        ExitCode = 0;
} catch (e) {
    if (fso.FileExists(tempInFileName)) {
        fso.DeleteFile(tempInFileName);
    }
    if (fso.FileExists(tempOutFileName)) {
        fso.DeleteFile(tempOutFileName);
    }
    throw e;
}

4.3 Configuring Custom Script Properties for Oracle BI Delivers

You set script properties on the Actions tab of an agent in Oracle BI Delivers. See Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition for details. Refer also to Section 3.5, "Modifying Agents in Job Manager."

Note:

The script has to exist on the Oracle BI Scheduler server computer before you can create the agent. Create the custom script, and then create the agent to call the script. See Section 4.4, "Creating a Custom Script Example - Copy Results to the File System."

To configure custom script properties for agents:

  1. On the Home page in Oracle BI EE, click the New menu and select the Agent option.

  2. Display the Conditions tab and select the Use a condition box.

  3. Click Create and Browse to select an analysis.

  4. Click OK.

  5. Click OK.

  6. Display the Actions tab.

  7. Click the Add New Action icon and select the Invoke Server Script menu option.

    The New Action - Invoke Server Script dialog is displayed.

  8. Click the Add Document Parameter icon.

  9. Select the first row of parameters and click the Delete button.

  10. Enter properties for the parameter displayed.

    For example, for the script that is shown in Section 4.4, "Creating a Custom Script Example - Copy Results to the File System," you use the values that are described in the following table.

    Field Value or Setting

    Language

    JavaScript

    Script Path

    createResultfile.js

    Name

    Enter a name for the parameter.

    Prompt

    Enter a prompt. For example "Result Set:"

    Value

    Select Value from the list. This maps a fixed value, for example, PDF.

    Select Condition Analysis

    Optional

    Clear the check box.


  11. Use the plus icon to display a new row for a second parameter.

  12. Enter Result Set Extension in the Prompt field.

  13. Enter .pdf into the Value field.

  14. Click OK.

  15. Save the agent.

    This script runs after the Conditional Request of the agent.

4.4 Creating a Custom Script Example - Copy Results to the File System

This example configures a script for the Oracle BI Scheduler that copies the results of an agent to another directory. The script copies the temporary file that contains the results of the Conditional Request to the agent log directory. The JobID, InstanceID, and UserID are used in the file name to guarantee that the result sets do not overwrite each other with each execution of the agent, for each user, or for other agents that share this script.

To add this job in an agent, see Section 4.3, "Configuring Custom Script Properties for Oracle BI Delivers."

The example script uses the following values:

  • The agent log directory on the Oracle BI Scheduler computer is $OracleBI\instances\logs\Agents (where $OracleBI is the location in which the Oracle Business Intelligence software is installed).

  • The agent is run as Administrator.

  • The Custom Script properties are set according to the table in Section 4.3, "Configuring Custom Script Properties for Oracle BI Delivers."

  • If the job ID is 101 and instance ID is 1208, then you see a file called 101-1208-Administrator-AgentScript1.pdf.

The output of this example, after the agent is run, is a file on the Oracle BI Scheduler computer called D:\OracleBI\Log\Agents\101-1208-Administrator-AgentScript1.PDF.

This file contains the results of the Conditional Request in PDF format.

For all script jobs from chained agents, the full path name to the temporary file is specified in Parameter(0).

/////////////////////////////////////////////////////////////
//
// createResultFile.js
// 
// Copies the results in the temporary file to a new file name
// 
// Parameter(0) = Agent Result File Path
// Parameter(1) = Last Part of Output File Name (no path)
//
/////////////////////////////////////////////////////////////
var FSO = new ActiveXObject("Scripting.FileSystemObject");
var fileName = GetConfigurationValue("Log Dir", "Agents") +
    "\\" + JobID + "-" + InstanceID + "-" + UserID + "-" +
    Parameter(1);
var fooFile = FSO.CopyFile(Parameter(0), fileName, true);

4.5 Oracle BI Scheduler Read-Only Script Object Properties

The Oracle BI Scheduler supports the read-only script object properties that are described in Table 4-1.

Table 4-1 Oracle BI Scheduler Read-Only Script Object Properties

Object Property Description Return Value Syntax

JobID

Returns the job identification number that is associated with this instance.

long

NA

InstanceID

Returns the instance identification number that is associated with this instance.

long

NA

ParameterCount

Returns the number of job parameters that is associated with the job script.

long

NA

Parameter (index)

Returns a specific parameter that is associated with the script. Parameter (index) returns an error if the given index is less than zero or greater than ParameterCountminus 1.

string

Parameter(index)

Index is the zero-based index of the parameter.

Script

Returns the Script object that represents the current script. This object implements the COM IDispatch interface and can be passed as arguments to methods of other objects that exist on the system. Implementing the COM IDispatch is particularly useful when handling cancel events to a running instance. See Section 4.8.6, "RegisterCancelCommand Method".

script object

NA

UserID

Returns the user identification number that is associated with the instance.

string

NA


4.6 Oracle BI Scheduler Read/Write Script Object Properties

The Oracle BI Scheduler supports the read/write script object properties that are shown in Table 4-2.

Table 4-2 Oracle BI Scheduler Read/Write Script Object Properties

Object Property Description Return Value

Message

Sets or returns the Message property of the running instance. The Message property can convey meaningful error information. Setting this value changes the Message field of a Job Instance without stopping execution of the current Job Script.

If the JScript throw() method is called and this property has been set, then the value is appended to the message description in the JScript or VBScript Error object.

COM objects that implement the IDispatch interface can be accessed from within Job Scripts. If any method fails and properly provides error information through the SetErrorInfo() method, then that information is contained in the Message field of the Job Instance. If the Message property is set before the COM object error is generated, then that string value is appended to the COM object error information.

string

Severity

Sets the instance status. You can set it to any of the Severity Constants, as described in Section 4.7.1, "Severity Constants.". By default, it is set to nqSeverityInformation.

string

ExitCode

Sets or returns the Exit Code property that is associated with the instance. The default is 0 (zero). See the description of ExitCode instance properties in Section 6.2.5, "Instance Properties in Job Manager."

long


4.7 Oracle BI Scheduler Script-Defined Constants

The Oracle BI Scheduler supports the following script-defined constants. These constants are used by the methods to schedule new jobs.

4.7.1 Severity Constants

This topic is part of Section 4.7, "Oracle BI Scheduler Script-Defined Constants."

Severity constants are used in the severity property of a Message (error message) returned by a script to determine the status of a job instance. Table 4-3 describes Severity values.

Table 4-3 Severity Constant Values

Value Description

nqSeverityInformation

Set the Severity property to Information if the Message contains only information for the job instance; that is, no error condition is reflected. The status of the instance is set to Completed. This is the default if Severity is not set.

nqSeverityWarning

Set the Severity property to Warning if the Message contains text that describes a non-critical failure. The instance status is set to Warning.

nqSeverityError

Set the Severity property to Error if the Message contains text that indicates a critical failure. The instance status is set to Failed.


4.7.2 DayEnum Constants

This topic is part of Section 4.7, "Oracle BI Scheduler Script-Defined Constants."

The DayEnum values are used with the scheduling functions to identify days in a month, from Day 1 to Day 31. Table 4-4 describes DayEnum values.

Table 4-4 DayEnum Constant Values

Value Description

nqDay1

Day 1

nqDay2

Day 2

nqDay3

Day 3

...

...

nqDay31

Day 31


4.7.3 DayOfWeekEnum Constants

This topic is part of Section 4.7, "Oracle BI Scheduler Script-Defined Constants."

The DayOfWeekEnum values are used with the scheduling functions to identify days in a week. Table 4-5 describes DayOfWeekEnum values.

Table 4-5 DayOfWeekEnum Constant Values

Value Description

nqSunday

Sunday

nqMonday

Monday

nqTuesday

Tuesday

nqWednesday

Wednesday

nqThursday

Thursday

nqFriday

Friday

nqSaturday

Saturday


4.7.4 JobFlagsEnum Constants

This topic is part of Section 4.7, "Oracle BI Scheduler Script-Defined Constants."

The JobFlagsEnum values are used with the scheduling methods of the Script object to control how a job behaves. Table 4-6 describes JobFlagsEnum values.

Table 4-6 JobFlagsEnum Constant Values

Value Description

nqJobNoFlags

This flag indicates that the job has no special behavior.

nqJobDeleteWhenDone

This flag indicates that the job is deleted when there are no more scheduled run times.

nqJobDisabled

This flag indicates that the job is disabled. This is useful for preventing a job from running at the scheduled time or times.

nqJobHasEndDate

This flag indicates that the job has a valid end date.

nqJobExecuteWhenMissed

If for some reason the Oracle BI Scheduler is down when the job is supposed to start, then this flag indicates that the job should run when the Oracle BI Scheduler starts again.

nqJobDeleteScriptWhenDone

When a job is removed and this flag is set, the script that is associated with the job is deleted. This is useful only with the nqJobScriptContainsPath flag.

nqJobScriptContainsPath

This flag indicates that the script that is associated with the job contains a path to a file that contains the actual script code.

nqJobStartNow

When this flag is set, the begin date and start time are ignored. Instead, these fields are set to the current time of the Oracle BI Scheduler.


4.7.5 MonthEnum Constants

This topic is part of Section 4.7, "Oracle BI Scheduler Script-Defined Constants."

The MonthEnum values are used with the scheduling functions to identify months. Table 4-7 describes MonthEnum values.

Table 4-7 MonthEnum Constant Values

Value Description

nqJanuary

January

nqFebruary

February

nqMarch

March

nqApril

April

nqMay

May

nqJune

June

nqJuly

July

nqAugust

August

nqSeptember

September

nqOctober

October

nqNovember

November

nqDecember

December


4.7.6 OccurrenceEnum Constants

This topic is part of Section 4.7, "Oracle BI Scheduler Script-Defined Constants."

The OccurrenceEnum values are used with the scheduling functions to identify the occurrence of a given day. Table 4-8 describes OccurrenceEnum values.

Table 4-8 OccurrenceEnum Constant Values

Value Description

nqFirst

First occurrence

nqSecond

Second occurrence

nqThird

Third occurrence

nqFourth

Fourth occurrence

nqLast

Last occurrence


4.8 Oracle BI Scheduler Script Object Methods and Events

You use script object methods and events for the Oracle BI Scheduler when writing programs, as described in Chapter 4, "Programming BI Scheduler VBScript and JScript Jobs." The following sections describe methods and events:

4.8.1 CreateArray Method

This topic is part of Section 4.8, "Oracle BI Scheduler Script Object Methods and Events."

Creates an Array object.

Usage: This method is provided only for JScript because local JScript Array objects cannot be passed directly to the Script methods. This method is called to create an array object and to pass the array object to Script methods that accept an array as an argument.

Syntax 1: Set array = CreateArray ()

Syntax 2: Set array = CreateArray (size)

Syntax 3: Set array = CreateArray (element 0, element 1, ..., element n)

The different syntax versions create arrays as follows:

  • Syntax 1 creates an array of size 0 (zero).

  • Syntax 2 creates an array with the specified size.

  • Syntax 3 creates an array filled with the specified elements.

Example 4-1 Example

var i;
var array1= CreateArray(2);
for (i = 0; i < array1.Size; i++)
{
   array1(i) = i;
}

   array1.Resize(4);
for (i = 2; i < array1.Size; i++)
{
   array1(i) = i;
}

var array2 = CreateArray(0, 1, 2,3);
for (i = 0; i < array2.Size; i++)
{
   if (array1(i) != array2(i))
   break;
}

Arguments: See Table 4-9 for CreateArray method arguments.

Return Value: Returns an Array object.

Table 4-9 CreateArray Method Arguments

Argument Description

size

A long value that specifies the initial size of the array.

element0 … elementn

The values to place in the array. This creates an array with the lower and upper bounds of 0 (zero) and n, respectively.


4.8.2 DeregisterCancelCommand Method

This topic is part of Section 4.8, "Oracle BI Scheduler Script Object Methods and Events."

Deregisters a previously registered cancel method.

Usage: Call this method to deregister the most recently registered cancel method after a long operation has completed successfully. You need not call this method if the script was canceled.

Syntax: DeregisterCancelCommand

4.8.3 GetConfigurationValue Method

This topic is part of Section 4.8, "Oracle BI Scheduler Script Object Methods and Events."

Returns the value in the configuration relative to the root registry entry of the Oracle BI Scheduler.

Usage: Returns the string value for a registry setting relative to the Oracle BI Scheduler. The configKey and subkeyPath strings must be identical to those in the registry.

Syntax: value = GetConfigurationValue(configKey [, subkeyPath])

Arguments: See Table 4-10 for GetConfigurationValue method arguments.

Return Value: Returns a string value.

Table 4-10 GetConfigurationValue Method Arguments

Argument Description

configKey

A string that specifies the registry key name to return.

subkeyPath

(Optional) A string value that specifies the registry path below the Oracle BI Scheduler's root path.


4.8.4 GetTempFileName Method

This topic is part of Section 4.8, "Oracle BI Scheduler Script Object Methods and Events."

Returns a temporary file name.

Usage: GetTempFileName() does not create a file. It only provides a temporary file name for use in creating a file. Files that are created in job scripts are not deleted automatically when the script terminates.

Syntax: tfname = GetTempFileName()

Return Value: Returns a string value.

4.8.5 LaunchProcess Method

This topic is part of Section 4.8, "Oracle BI Scheduler Script Object Methods and Events."

Executes a command line in a new process.

Usage: Call this method to execute a command line in a new process. If the wait argument is set to True, then this method returns the exit code that is returned by the process.

Syntax: exitcode = LaunchProcess ( commandLine [, wait, terminateOnCancel] )

Arguments: See Table 4-11 for LaunchProcess method arguments.

Return Value: Returns a long value.

Table 4-11 LaunchProcess Method Arguments

Argument Description

commandLine

A string that specifies the command line to execute.

wait

(Optional) A Boolean value that specifies whether the method should wait for the process to terminate. The default is True.

terminateOnCancel

(Optional) A Boolean value that specifies whether the method should terminate the process when the script is canceled. The default is True.


4.8.6 RegisterCancelCommand Method

This topic is part of Section 4.8, "Oracle BI Scheduler Script Object Methods and Events."

Registers a method to be called when the script is canceled.

Usage: Occasionally, an object's method takes a long time to complete. If the job is canceled before the call returns, then the script engine still must wait until the call returns. This could potentially take hours and limit resources. This method solves the problem by registering a method that is asynchronously called by the script engine if the script gets canceled.

Cancel methods should be registered before calling the method that executes a long operation. When the method returns, the cancel method should be deregistered by calling DeregisterCancelCommand().

A good practice is to hide implementation details of a COM object from the caller, having the COM object itself handle all registration and deregistration of cancel commands. Pass an instance of the Script object to the COM object, then call the RegisterCancelCommand() and DeregisterCancelCommand() methods because the Script object implements the IDispatch interface.

Syntax: RegisterCancelCommand source, methodName [, arguments]...

Arguments: See Table 4-12 for RegisterCancelCommand method arguments.

Table 4-12 RegisterCancelCommand Method Arguments

Argument Description

source

An object whose method is being registered.

methodName

A string that specifies the method name.

arguments

Optional arguments to be passed into the method.


4.8.7 ScheduleJobDaily Method

This topic is part of Section 4.8, "Oracle BI Scheduler Script Object Methods and Events."

Schedules a new job with a Daily trigger.

Syntax: ScheduleJobDaily name, description, scriptType, script, startDate, startTime, endTime, minutesInterval, daysInterval [, parameters, flags, maxRunTimeMS, maxConcurrentInstances, endDate]

Arguments: See Table 4-13 for ScheduleJobDaily method arguments.

Table 4-13 ScheduleJobDaily Method Arguments

Argument Description

name

A string that specifies the name of the job.

description

A string that specifies the description of the job.

scriptType

A string that specifies the script type that is associated with the job (either VBScript or JScript).

script

A string that specifies the script code or path (if the nqJobScriptContainsPath flag is set) that is associated with the job.

startDate

A date value that specifies the date that the job is activated.

startTime

A date value that specifies the time that the job is activated.

endTime

A date value that specifies the time that the job is deactivated.

minutesInterval

A long value that specifies the number of minutes between consecutive job executions.

daysInterval

An integer value that specifies the number of days between job invocations.

parameters

(Optional) A string array of parameter values that is passed to the script. The default is an empty array.

flags

(Optional) A long value that specifies the flags that are associated with the job. For valid settings, see Section 4.7.4, "JobFlagsEnum Constants". The default is nqJobNoFlags.

maxRunTimeMS

(Optional) A long value that specifies the maximum time in milliseconds that a job runs before it is terminated. The default is 0 (zero), which means the job can run indefinitely.

maxConcurrentInstances

(Optional) A long value that specifies the maximum number of concurrent running instances of this job. The default is 0 (zero), which means no limit.

endDate

(Optional) A date value that specifies the time that the job is deactivated.


4.8.8 ScheduleJobMonthlyDate Method

This topic is part of Section 4.8, "Oracle BI Scheduler Script Object Methods and Events."

Schedules a new job with a Monthly by Date trigger.

Syntax: ScheduleJobMonthlyDate name, description, scriptType, script, startDate, startTime, endTime, minutesInterval, whichDays, whichMonths [, parameters, flags, maxRunTimeMS, maxConcurrentInstances, endDate]

Arguments: See Table 4-14 for ScheduleJobMonthlyDate method arguments.

Table 4-14 ScheduleJobMonthlyDate Method Arguments

Argument Description

name

A string that specifies the name of the job.

description

A string that specifies the description of the job.

scriptType

A string that specifies the script type that is associated with the job (either VBScript or JScript).

script

A string that specifies the script code or path (if the nqJobScriptContainsPath flag is set) that is associated with the job.

startDate

A date value that specifies the date that the job is activated.

startTime

A date value that specifies the time that the job is activated.

endTime

A date value that specifies the time that the job is deactivated.

minutesInterval

A long value that specifies the number of minutes between consecutive job executions.

whichDays

An long value that specifies the days of the month on which the job runs. For valid settings, see Section 4.7.2, "DayEnum Constants."

whichMonths

An integer value that specifies the months in which the job runs. For valid settings, see Section 4.7.5, "MonthEnum Constants."

parameters

(Optional) A string array of parameter values that is passed to the script. The default is an empty array.

flags

(Optional) A long value that specifies the flags that are associated with the job. For valid settings, see Section 4.7.4, "JobFlagsEnum Constants." The default is nqJobNoFlags.

maxRunTimeMS

(Optional) A long value that specifies the maximum time in milliseconds that a job runs before it is terminated. The default is 0 (zero), which means the job can run indefinitely.

maxConcurrentInstances

(Optional) A long value that specifies the maximum number of concurrent running instances of this job. The default is 0 (zero), which means no limit.

endDate

(Optional) A date value that specifies the time that the job is deactivated.


4.8.9 ScheduleJobMonthlyDOW Method

This topic is part of Section 4.8, "Oracle BI Scheduler Script Object Methods and Events."

Schedules a new job with a monthly by day of the week (DOW) trigger.

Syntax: ScheduleJobMonthlyDOW name, description, scriptType, script, startDate, startTime, endTime, minutesInterval, whichOccurrences, whichDays, whichMonths [, parameters, flags, maxRunTimeMS, maxConcurrentInstances, endDate]

Arguments: See Table 4-15 for ScheduleJobMonthlyDOW method arguments.

Table 4-15 ScheduleJobMonthlyDOW Method Arguments

Argument Description

name

A string that specifies the name of the job.

description

A string that specifies the description of the job.

scriptType

A string that specifies the script type that is associated with the job (either VBScript or JScript).

script

A string that specifies the script code or path (if the nqJobScriptContainsPath flag is set) that is associated with the job.

startDate

A date value that specifies the date that the job is activated.

startTime

A date value that specifies the time that the job is activated.

endTime

A date value that specifies the time that the job is deactivated.

minutesInterval

A long value that specifies the number of minutes between consecutive job executions.

whichOccurrences

An integer value that specifies the occurrences of days of the week on which the job runs. For valid settings, see Section 4.7.2, "DayEnum Constants".

whichDays

An integer value that specifies the days of the week on which the job runs. For valid settings, see Section 4.7.3, "DayOfWeekEnum Constants".

whichMonths

An integer value that specifies the months in which the job runs. For valid settings, see Section 4.7.5, "MonthEnum Constants".

parameters

(Optional) A string array of parameter values that is passed to the script. The default is an empty array.

flags

(Optional) A long value that specifies the flags that are associated with the job. For valid settings, see Section 4.7.4, "JobFlagsEnum Constants". The default is nqJobNoFlags.

maxRunTimeMS

(Optional) A long value that specifies the maximum time in milliseconds that a job runs before it is terminated. The default is 0 (zero), which means the job can run indefinitely.

maxConcurrentInstances

(Optional) A long value that specifies the maximum number of concurrent running instances of this job. The default is 0 (zero), which means no limit.

endDate

(Optional) A date value that specifies the time that the job is deactivated.


4.8.10 ScheduleJobNow Method

This topic is part of Section 4.8, "Oracle BI Scheduler Script Object Methods and Events."

Schedules a new job with a Run Now trigger.

Syntax: ScheduleJobNow name, description, scriptType, script [, parameters, flags, maxRunTimeMS]

Arguments: See Table 4-16 for ScheduleJobNow method arguments.

Table 4-16 ScheduleJobNow Method Arguments

Argument Description

name

A string that specifies the name of the job.

description

A string that specifies the description of the job.

scriptType

A string that specifies the script type that is associated with the job (either VBScript or JScript).

script

A string that specifies the script code or path (if the nqJobScriptContainsPath flag is set) that is associated with the job.

parameters

(Optional) A string array of parameter values that is passed to the script. The default is an empty array.

flags

(Optional) A long value that specifies the flags that are associated with the job. For valid settings, see Section 4.7.4, "JobFlagsEnum Constants". The default is nqJobNoFlags.

maxRunTimeMS

(Optional) A long value that specifies the maximum time in milliseconds that a job runs before it is terminated. The default is 0 (zero), which means the job can run indefinitely.


4.8.11 ScheduleJobOnce Method

This topic is part of Section 4.8, "Oracle BI Scheduler Script Object Methods and Events."

Schedules a new job with a Run Once trigger.

Syntax: ScheduleJobOnce name, description, scriptType, script, startDate, startTime [, parameters, flags, maxRunTimeMS]

Arguments: See Table 4-17 for ScheduleJobOnce method arguments.

Table 4-17 ScheduleJobOnce Method Arguments

Argument Description

name

A string that specifies the name of the job.

description

A string that specifies the description of the job.

scriptType

A string that specifies the script type that is associated with the job (either VBScript or JScript).

script

A string that specifies the script code or path (if the nqJobScriptContainsPath flag is set) that is associated with the job.

startDate

A date value that specifies the date that the job is activated.

startTime

A date value that specifies the time that the job is activated.

parameters

(Optional) A string array of parameter values that is passed to the script. The default is an empty array.

flags

(Optional) A long value that specifies the flags that are associated with the job. For valid settings, see Section 4.7.4, "JobFlagsEnum Constants". The default is nqJobNoFlag.

maxRunTimeMS

(Optional) A long value that specifies the maximum time in milliseconds that a job runs before it is terminated. The default is 0 (zero), which means the job can run indefinitely.


4.8.12 ScheduleJobWeekly Method

This topic is part of Section 4.8, "Oracle BI Scheduler Script Object Methods and Events."

Schedules a new job with a Weekly trigger.

Syntax: ScheduleJobWeekly name, description, scriptType, script, startDate, startTime, endTime, minutesInterval, weeksInterval, whichDays [, parameters, flags, maxRunTimeMS, maxConcurrentInstances, endDate]

Argument: See Table 4-18 for ScheduleJobWeekly method arguments.

Table 4-18 ScheduleJobWeekly Method Arguments

Argument Description

name

A string that specifies the name of the job.

description

A string that specifies the description of the job.

scriptType

A string that specifies the script type that is associated with the job (either VBScript or JScript).

script

A string that specifies the script code or path (if the nqJobScriptContainsPath flag is set) that is associated with the job.

startDate

A date value that specifies the date that the job is activated.

startTime

A date value that specifies the time that the job is activated.

endTime

A date value that specifies the time that the job is deactivated.

minutesInterval

A long value that specifies the number of minutes between consecutive job executions.

weeksInterval

An integer value that specifies the number of weeks between job invocations.

whichDays

An integer value that specifies the days of the week on which the job runs. See Section 4.7.3, "DayOfWeekEnum Constants" for valid settings.

parameters

(Optional) A string array of parameter values that is passed to the script. The default is an empty array.

flags

(Optional) A long value that specifies the flags that are associated with the job. For valid settings, see Section 4.7.4, "JobFlagsEnum Constants". The default is nqJobNoFlags.

maxRunTimeMS

(Optional) A long value that specifies the maximum time in milliseconds that a job runs before it is terminated. The default is 0 (zero), which means the job can run indefinitely.

maxConcurrentInstances

(Optional) A long value that specifies the maximum number of concurrent running instances of this job. The default is 0 (zero), which means no limit.

endDate

(Optional) A date value that specifies the time that the job is deactivated.


4.8.13 OnError Event

This topic is part of Section 4.8, "Oracle BI Scheduler Script Object Methods and Events."

Occurs when the script engine encounters a run-time error while executing the script. This is intended for cleanup purposes, but the creative use of try/catch blocks in JScript and appropriate Error Handling in VBScript are often superior alternatives to using this event.

Usage: The script engine calls this procedure when it encounters a run-time error while executing the script. Define this procedure in your script to perform cleanup activities before the script terminates, such as deleting temporary files and releasing resources.

Syntax: OnError

Example 4-2 Using VBScript:

Public Sub OnError()
   LogFile.WriteLine "Encountered a runtime error in the script."
LogFile.Close
End Sub

Example 4-3 Using JScript:

function OnError()
{
   LogFile.WriteLine("Encountered a runtime error in the
   script.");
LogFile.Close();

4.9 Troubleshooting JScript and VBScript Job Failures

If a JScript or VBScript job fails with the error "nQSError: 66001] Failed to create the ActiveX scripting engine.", then the required script engine (VBScript or JScript) is not available or is broken on this computer.

You can reregister the script DLL files in Windows by running the command "regsvr32 vbscript.dll" for a VBScript failure or "regsvr32 jscript.dll" for a JScript failure. If these return the message "failed module could not be found", then you must repair the Windows installation to re-instate the missing DLL files. You can achieve this by rolling back to a restore point, or by carrying out a repair using the original operating system installation discs.