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.
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 SaturdayMonthEnum
The MonthEnum values are used with the scheduling functions to identify months. Table 17 describes MonthEnum values.
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 occurrenceDayEnum
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 31Script 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:
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
InstancesOptional. 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
InstancesOptional. 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
InstancesOptional. 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
InstancesOptional. 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:
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:
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
andsubkeyPath
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 SubExample in JScript:
function OnError()
{
LogFile.WriteLine("Encountered a runtime error in the
script.");
LogFile.Close();
}
Bookshelf Home | Contents | Index | Search | PDF |
Siebel Analytics Scheduler Guide Published: 18 April 2003 |