Bookshelf Home | Contents | Index | Search | PDF

Siebel Analytics Scheduler Guide > Using Siebel Analytics Scheduler > Working with Job Scripts >

Working with the Script Object

---

Siebel Analytics 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.

Read-Only Script Object Properties

This section describes the read-only script object properties.

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 COM objects that exist on the system. This is particularly useful when handling cancel events to a running instance. See RegisterCancelCommand.

Return Value: returns a script object.

JobID

Returns the job identification number associated with this instance.

Return Value: returns a long value.

InstanceID

Returns the instance identification number associated with this instance.

Return Value: returns a double value.

UserID

Returns the user identification number associated with the instance.

Return Value: returns a string value.

Parameter Count

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

Return Value: returns a long value.

Parameter (index)

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

Syntax:

Parameter(index)

where:

index is the zero-based index of the parameter.

Return Value: returns a string value.

Read/Write Script Object Properties

This section describes the read/write script object properties.

Error Message

Sets or returns the Error Message property of the running instance.

In UNIX environments, the JScript throw() construct is not supported. Instead, the ErrorMessage property can be used to convey meaningful error information. Setting this value changes the Error Message field of a Job Instance. However, unlike throw(), it does not stop execution of the current Job Script.

In Windows environments, if the JScript throw() method is called and this property has been set, 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, that information will be contained in the Error Message field of the Job Instance. If the ErrorMessage property is set before the COM object error is generated, then that string value is appended to the COM object error information.

Be aware that if this property is set to a nonempty string value, the job instance will have a Failed status and its ErrorMessage property will be set. Resetting this value to the empty string ("") will clear the error messages.

Settings and Return Value: sets or returns a string value.

ExitCode

Sets or returns the Exit Code property associated with the instance.

Settings and Return Value: sets or returns a long value. The default is 0 (zero).

Script-Defined Constants

This section describes the script-defined constants. These constants are used by the methods that allow a script to schedule new jobs.

JobFlagsEnum

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

Table 15. JobFlagsEnum  alues

Constant	Description
nqJobNoFlags	Job has no special behavior.
nqJobDeleteWhenDone	Job is deleted when there are no more scheduled run times.
nqJobDisabled	Job is disabled. This is useful for preventing a job from running at the scheduled time or times.
nqJobHasEndDate	Job has a valid end date.
nqJobExecuteWhenMissed	If for some reason Siebel Analytics Scheduler is down when the job is supposed to start, this flag indicates that the job should run when the Scheduler starts up again.
nqJobDeleteScriptWhenDone	When a job is removed and this flag is set, the script associated with the job is deleted. This is useful only in conjunction with the nqJobScriptContainsPath flag.
nqJobScriptContainsPath	This flag indicates that the script associated with the job contains a path to a file containing the actual script code.
nqJobStartNow	When this flag is set, the begin date and start time are ignored. Instead, these fields get set to the current time of Siebel Analytics Scheduler.
nqJobIsUserScript	When scheduling another job from within a script, this flag specifies that the NQSConnect() function will be disabled (the job is not a trusted job). This action effectively sets the nqJobIsUserScript flag for any job that the newly scheduled job may schedule.

DayOfWeekEnum

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

Table 16. DayOfWeekEnum Values

Constant	Description
nqSunday	Sunday
nqMonday	Monday
nqTuesday	Tuesday
nqWednesday	Wednesday
nqThursday	Thursday
nqFriday	Friday
nqSaturday	Saturday

MonthEnum

The MonthEnum values are used with the scheduling functions to identify months. Table 17 describes MonthEnum values.

Table 17. MonthEnum Values

Constant	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

OccurrenceEnum

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

Table 18. OccurrenceEnum Values

Constant	Description
nqFirst	First occurrence
nqSecond	Second occurrence
nqThird	Third occurrence
nqFourth	Fourth occurrence
nqLast	Last occurrence

DayEnum

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

Table 19. DayEnum Values

Constant	Description
nqDay1	Day 1
nqDay2	Day 2
nqDay3	Day 3
...	...
nqDay31	Day 31

Script Object Methods

This section describes the script object methods.

RegisterCancelCommand

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

Syntax:

RegisterCancelCommand source, methodName [, arguments]...

where:

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.

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

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

Since it is often good practice to hide implementation details of a COM object from the caller, consider having the COM object itself handle all registration and deregistration of cancel commands. A COM object should allow the script writer to pass it an instance of the Script object to the COM object. The COM object could then call the RegisterCancelCommand() and DeregisterCancelCommand() methods because the Script object implements the IDispatch interface.

DeregisterCancelCommand

Deregisters a previously registered cancel method.

Syntax:

DeregisterCancelCommand

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

NQSConnect

Opens a connection to a Siebel data source and returns a Siebel object.

Syntax:

Set nqs = NQSConnect ( dsn [, timeout] )

where:

dsn	A String that specifies the data source name to connect to.
timeout	Optional. A Long value that specifies the number of seconds to wait for the connection to open. The default is 30. Specifying 0 (zero) will wait indefinitely.

Return Value: Returns a Siebel object.

Usage Notes: Call this method to connect to a Siebel data source. Once connected, you can use the Siebel object's properties and methods to send queries and retrieve records. See Working with the Siebel Object for more information.

Please note that this method is not available for jobs that are not trusted (that is, the nqJobIsUserScript flag is set).

ScheduleJobNow

Schedules a new job with a Run Now trigger.

Syntax:

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

where:

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 associated with the job (either VBScript or JScript).
script	A string that specifies the script code or path (if the nqJobScriptContainsPath flag is set) associated with the job.
parameters	Optional. A string array of parameter values passed to the script. The default is an empty array.
flags	Optional. A long value that specifies the flags associated with the job. For valid settings, see JobFlagsEnum. The default is nqJobNoFlags.
maxRunTimeMS	Optional. A long value that specifies the maximum time, in milliseconds, a job is allowed to run before it is terminated. The default is 0 (zero), which means the job can run indefinitely.

ScheduleJobOnce

Schedules a new job with a Run Once trigger.

Syntax:

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

where:

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 associated with the job (either VBScript or JScript).
script	A string that specifies the script code or path (if the nqJobScriptContainsPath flag is set) associated with the job.
startDate	A date value that specifies the date the job is activated.
startTime	A date value that specifies the time the job is activated.
parameters	Optional. A string array of parameter values passed to the script. The default is an empty array.
flags	Optional. A long value that specifies the flags associated with the job. For valid settings, see JobFlagsEnum. The default is nqJobNoFlag.
maxRunTimeMS	Optional. A long value that specifies the maximum time, in milliseconds, a job is allowed to run before it is terminated. The default is 0 (zero), which means the job can run indefinitely.

ScheduleJobDaily

Schedules a new job with a Daily trigger.

Syntax:

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

where:

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 associated with the job (either VBScript or JScript).
script	A String that specifies the script code or path (if the nqJobScriptContainsPath flag is set) associated with the job.
startDate	A date value that specifies the date the job is activated.
startTime	A date value that specifies the time the job is activated.
endTime	A date value that specifies the time 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 passed to the script. The default is an empty array.
flags	Optional. A long value that specifies the flags associated with the job. For valid settings, see JobFlagsEnum. The default is nqJobNoFlags.
maxRunTimeMS	Optional. A long value that specifies the maximum time, in milliseconds, a job is allowed to run before it is terminated. The default is 0 (zero), which means the job can run indefinitely.
maxConcurrent Instances	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 the job is deactivated.

ScheduleJobWeekly

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]

where:

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 associated with the job (either VBScript or JScript).
script	A string that specifies the script code or path (if the nqJobScriptContainsPath flag is set) associated with the job.
startDate	A date value that specifies the date the job is activated.
startTime	A date value that specifies the time the job is activated.
endTime	A date value that specifies the time 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 week the job runs. See DayOfWeekEnum values for valid settings.
parameters	Optional. A string array of parameter values passed to the script. The default is an empty array.
flags	Optional. A long value that specifies the flags associated with the job. For valid settings, see JobFlagsEnum. The default is nqJobNoFlags.
maxRunTimeMS	Optional. A long value that specifies the maximum time, in milliseconds, a job is allowed to run before it is terminated. The default is 0 (zero), which means the job can run indefinitely.
maxConcurrent Instances	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 the job is deactivated.

ScheduleJobMonthlyDate

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]

where:

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 associated with the job (either VBScript or JScript).
script	A string that specifies the script code or path (if the nqJobScriptContainsPath flag is set) associated with the job.
startDate	A date value that specifies the date the job is activated.
startTime	A date value that specifies the time the job is activated.
endTime	A date value that specifies the time 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 the job runs. For valid settings, see DayEnum.
whichMonths	An integer value that specifies the months the job runs. For valid settings, see MonthEnum.
parameters	Optional. A string array of parameter values passed to the script. The default is an empty array.
flags	Optional. A long value that specifies the flags associated with the job. For valid settings, see JobFlagsEnum. The default is nqJobNoFlags.
maxRunTimeMS	Optional. A long value that specifies the maximum time, in milliseconds, a job is allowed to run before it is terminated. The default is 0 (zero), which means the job can run indefinitely.
maxConcurrent Instances	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 the job is deactivated.

ScheduleJobMonthlyDOW

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]

where:

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 associated with the job (either VBScript or JScript).
script	A string that specifies the script code or path (if the nqJobScriptContainsPath flag is set) associated with the job.
startDate	A date value that specifies the date the job activated.
startTime	A date value that specifies the time the job is activated.
endTime	A date value that specifies the time 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 week the job runs. For valid settings, see DayEnum.
whichDays	An integer value that specifies the days of week the job runs. For valid settings, see DayOfWeekEnum.
whichMonths	An integer value that specifies the months the job runs. For valid settings, see MonthEnum.
parameters	Optional. A string array of parameter values passed to the script. The default is an empty array.
flags	Optional. A long value that specifies the flags associated with the job. For valid settings, see JobFlagsEnum. The default is nqJobNoFlags.
maxRunTimeMS	Optional. A long value that specifies the maximum time, in milliseconds, a job is allowed to run before it is terminated. The default is 0 (zero), which means the job can run indefinitely.
maxConcurrent Instances	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 the job is deactivated.

CreateArray

Creates an Array object.

Syntax:

Syntax 1          Set array = CreateArray ()

Syntax 2          Set array = CreateArray ( size )

Syntax 3          Set array = CreateArray ( element0, element1, ..., elementn)

where:

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.

Return Value: returns an Array object.

Usage Notes: 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 pass the array object to Script methods that accept an array as arguments.

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:

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;
}

LaunchProcess

Executes a command line in a new process.

Syntax:

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

where:

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.

Return Value: returns a long value.

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

GetTempFileName

Returns a temporary file name.

Syntax:

tfname = GetTempFileName()

Return Value: returns a string value.

Usage Notes: GetTempFileName() does not create a file. It only provides a temporary file name that can be used to create a file. Files created in job scripts are not deleted automatically when the script terminates.

GetConfigurationValue

Returns the value in Siebel Analytics Scheduler configuration relative to the Scheduler's root registry entry.

Syntax:

value = GetConfigurationValue(configKey [, subkeyPath])

where:

configKey	A string that specifies the registry key name to return.
subkeyPath	Optional. A string value that specifies the registry path below the Scheduler's root path.

Return Value: returns a string value.

Usage Notes: GetConfigurationValue() returns the string value for a registry setting relative to Siebel Analytics Scheduler. The configKey and subkeyPath strings must be identical to those in the registry.

Script Object Events

This section describes the script object events.

OnError

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

Syntax:

OnError

Usage Notes: The script engine calls this procedure when it encounters a runtime error while executing the script. Define this procedure in your script if you want to perform some cleanup activities before the script terminates, such as deleting temporary files and releasing resources.

Example in VBScript:

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

Example in JScript:

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

Bookshelf Home | Contents | Index | Search | PDF