7
Job Scheduling Integration

This chapter covers the Job Scheduling system Interface. It describes:

• Submitting a Job
• Deleting a Batch Job
• Job Notification
• Job Scripting
• Job Scheduling API Reference
• VoxJobNotifyUnpacker Class and Methods

Submitting a Job

The Job Scheduling system interface allows you to submit both batch and interactive jobs. The steps for creating and submitting a job depend on whether the job is a batch job or an interactive job. See Submitting a Batch Job on page 7-2 or Submitting an Interactive Job on page 7-3.

Submitting a Batch Job

A batch job is one that is submitted to the Job Scheduling system. The Enterprise Manager Console gathers the job's details and schedules the job with the agent on the node on which the job will run. A batch job can be scheduled to run more than once according to a specified schedule. All batch jobs can be observed from the Console.

Note:

Unless it is read-only, an externally-submitted batch job can be deleted from the Console.

To submit a batch job:

1. Create a OraTcl job script for the job. See Chapter 9, "Jobs and Events Scripts" for more information about writing job scripts.
2. Copy the job's script to an accessible directory. Place a copy of the script in a directory on a file system accessible to the Console.
3. Create and initialize a job object, as described in Initialize on page 7-9. When submitting a new batch job, set JobID to zero and Batch to TRUE in the call to Initialize. If you want to create a read-only job, set the ReadOnly parameter to TRUE.
4. Submit the job details, setting the destinations first. The functions available for specifying job details are:
   1. SetDestinationsEx to submit the services or nodes on which to run the job, as well as to specify parameters for each destination and the names of the input files. See SetDestinationsEx on page 7-12.
   2. SetScript to submit the name of the script for the job. See SetScript on page 7-19.
   3. SetJobName to provide a clear-text name for the Console to display when referring to the job. See SetJobName on page 7-13.
   4. SetSchedule to set the job schedule. See SetSchedule on page 7-15.
   5. SetNotificationObjectProgID to submit the class name of the OLE automation server to receive notifications about the job (optional). See SetNotificationObjectProgID on page 7-14.
   6. SetCredentials to specify the host username and password for the job. See SetCredentials on page 7-11.
5. Commit the job and store the JobID if you plan to coordinate job notifications. See Commit on page 7-8.
6. Process the job notifications as they return if SetNotificationObjectProgID was called.

Submitting an Interactive Job

An interactive job is one that is submitted and executed immediately. Typically these are jobs that require the application user to wait until the job is completed. When an interactive job is submitted, the communication daemon tries to contact the agent immediately. If the daemon cannot contact the agent, the job fails.

Interactive jobs are not logged in the same way as batch jobs. From the Console user's point of view these jobs do not exist. These jobs provide a service for other applications, such as database backup or recovery. Only the third-party application user sees that the application has performed an action on a remote node.

To submit an interactive job:

1. Create a OraTcl job script for the job. See Chapter 9, "Jobs and Events Scripts" for more information about writing job scripts.
2. Copy the job's script to an accessible directory. Place a copy of the script in a directory on a file system accessible to the Console.
3. Create and initialize a job object. Initialize a job object, as described in Initialize on page -9. Because you are submitting an interactive job, set JobID to zero, and Batch and ReadOnly to FALSE in the call to Initialize.
4. Submit the job details, setting destinations first. The functions available for specifying job details are:
   1. SetDestinationsEx to submit the service or node on which to run the job, as well as to specify parameters for each destination and the names of the input files. See SetDestinationsEx on page 7-12.
   2. SetScript to submit the fully qualified name of the script. See SetScript on page 7-19.
   3. SetNotificationObjectProgID to submit the name of the OLE automation server to receive notifications about the job. See SetNotificationObjectProgID on page 7-14.

Note:

SetNotificationObjectProgID is required for interactive jobs.

1. SetCredentials (optional) to submit the username and password to be used for the job. See SetCredentials on page 7-11.

Note:

SetCredentials is optional for interactive jobs. If you do not explicitly set the job credentials, the Console submits the job using the preferred credentials specified for the target destination.

1. Commit the job. For an interactive job, the call to the function Commit causes the daemon to contact the appropriate agent and submit the interactive job immediately. If the daemon successfully passes the job to the agent, it passes back a VOXJOB_STATUS_SCHEDULED notification. If the daemon is unsuccessful, it passes back an error code. See Commit on page 7-8.

Deleting a Batch Job

Only batch jobs can be deleted. If a job is currently running when it is deleted, the agent will kill the process running the job. If you are deleting a job that was created with a service to be notified when the job's status changed, then you will receive a notification with the status VOXJOBNT_STATUS_DELETED when the job has been deleted. To delete a batch job:

1. Initialize a job object. Initialize a job object, as described in Submitting a Batch Job on page 7-2. Set JobID to the ID of the job you want to delete and Batch to TRUE in the call to Initialize.
2. Delete the job. Call the function DeleteJob to delete a job.

Note:

Interactive jobs cannot be deleted.

Job Notification

In order to submit an interactive job or to receive messages about status changes for batch jobs, an OLE automation server that exposes a JobNotification method must be exposed by your application.

If you configure the job to receive notifications, then the job's output and any output parameters can be returned to you. If you do not, the Job Scheduling system will not notify you programmatically of any changes in the job's status, nor will it return any output parameters to you.

Extracting Job Notification Information

Use the helper function VoxJobNotifyUnpacker to extract all the information from the VARIANT passed to your application's JobNotification method.

Flushing the Job Queue

When an application is launched, use the function RegisterApplication to inform the Job Scheduling system to send any notifications that have been pending since an application had last run.

Who Is Notified

Just as in event notifications (see Notification on page 8-3), jobs are referenced by ProgID and current Console user. This ensures that a user receives only notifications from the jobs that the user submits and that each application maintains its own notification queue. The application does not have to pass the console username because the Console already knows it.

Job Notification Messages

When you submit a job, you will receive one of the following notifications:

• VOXEXT_JOB_STATUS_SUBMITTED if the submission succeeds.
• VOXEXT_JOB_STATUS_FAILED if it did not.

When a job initiates, you will receive a VOXEXT_JOB_STATUS_STARTED notification. Next you will receive one of the following notifications:

• VOXEXT_JOB_STATUS_COMPLETED if the job succeeded.
• VOXEXT_JOB_STATUS_FAILED if it failed.

This sequence will continue to repeat itself for batch jobs which have repeating schedules. After the last scheduled job execution completes, whether successfully or not, you will receive a VOXEXT_JOB_STATUS_EXPIRED notification, which is the last notification in the sequence for any given job. Note that you still get VOXEXT_JOB_STATUS_EXPIRED notifications for one-time or immediate jobs, including all interactive jobs.

After the successful deletion of a batch job, you receive a VOXEXT_JOB_STATUS_CANCELED notification.

Intermediate job status is not a part of the typical sequence of job notifications. It is provided for applications which want to record the progress or intermediate status of a job in the middle of its execution. The VOXEXT_JOB_STATUS_INTERMED notification is sent only when a job script containing the orajobstat OraTcl verb is invoked. For information on orajobstat, in see OraTcl Functions and Parameters on page 9-11. For an example of the use of orajobstat, see the intermed.tcl sample script in the ORACLE_HOME\SYSMAN\SDK\TCL directory.

Job Scripting

Every job is a Tcl script that is executed by the Oracle Intelligent Agent on a particular node. Jobs cannot be executed on nodes which do not have an agent running. Jobs are categorized in the Job Scheduling system of the Console according to different service types, such as database or listener jobs. However, all jobs are fundamentally node jobs and categories simply signify the script's effects. The credentials specified using the SetCredentials API are the node credentials with which the Tcl script executes.

The Tcl script does not get executed as if it were executed directly in the Tcl shell on that node. The Tcl scripts are framed within a Tcl program called the Master Tcl Script by the Job Scheduling system before the script gets sent to the agent. The Master Tcl script sets up the majority of the environment needed for jobs sent from the Enterprise Manager Console's user interface. However, there are some side effects of the Master Tcl Script environment that you can take advantage of. For example, the following variables are defined for your use:

Table 7-1 Tcl Variables

If a job needs to send files other than the actual Tcl script, send them as input files. You can specify these files using the SetScript API. One example is a Tcl job script that executes SQL and uses input files that contain SQL scripts. Another example is a job that invokes SQL*Plus with a SQL script, or Export with a specification file.

Input files get copied to the destination's node from the location specified on the console file system. You can find out the names of the input files on the destination's file system by referencing the OraTcl array oramsg(orainput). oramsg(orainput), defined for jobs only, is a Tcl list that contains the names of the job's input files. For more information on oramsg, see oramsg Elements on page 9-6.

Sending Jobs that Execute SQL*Plus Scripts

The file exec_sql.tcl is included in the SDK to provide jobs that execute SQL*Plus scripts. To send a job which does this, specify exec_sql.tcl with a fully qualified path as the script for a specific job in the ScriptName parameter to the SetScript API, and pass in the fully qualified path name of the SQL*Plus script to be executed as the sole input file in the InputFilenames parameter. The output of the SQL*Plus script will be sent to the application via the JobNotification mechanism as the output string in the VOXEXT_JOB_STATUS_COMPLETED notification.

Job Scheduling API Reference

The following section describes the external interface calls for the Job Scheduling system.

• Commit
• DeleteJob
• Initialize
• JobNotification
• RegisterApplication
• SetCredentials
• SetDestinationsEx
• SetNotificationObjectProgID
• SetSchedule
• SetJobName
• SetScript

Commit

Purpose

Commit causes the job object to schedule the job.

Syntax

VT_BOOL Commit(VTS_PI4 pJobID)

Parameters

pJobID

VTS_PI4

IN/OUT

pJobID

The unique identifier for a job.

Comments

If Commit is not called, the job is not submitted. This function returns a TRUE if it succeeds, otherwise it returns FALSE. pJobID is passed out after the commit has succeeded.

For an example illustrating how to use Commit, see CJobBatchCreateDlg::DoCommit in the jobbatch.cpp file.

DeleteJob

Purpose

DeleteJob allows for the deletion and the removal of the job from the remote nodes schedule.

Syntax

VT_BOOL DeleteJob()

Parameters

None

Comments

Interactive jobs cannot be deleted. This function returns a TRUE if it succeeds, otherwise it returns FALSE.

Note:

Initialize must be called before DeleteJob.

Initialize

Purpose

Initialize initializes a newly-created a job object.

Syntax

VT_BOOL Initialize(VTS_I4 JobID, 

                VTS_BOOL Batch, 

                VTS_BOOL ReadOnly)

Parameters

JobID

VTS_I4

IN

Batch

VTS_BOOL

IN

ReadOnly

VTS_BOOL

IN

JobID

The unique identifier for a job. Set to zero to create a new job.

Batch

Indicates whether the job is an interactive or batch job. This parameter only applies if JobID is zero.

ReadOnly

Indicates whether the job can be modified by the Console user or not. This parameter only applies if the job is batch and JobID is zero.

Comments

If you are initializing the job object in order to create a job, set JobID to zero. If you are initializing the job object in order to delete a job, then set JobID to the ID of the job you plan to delete. This is the JobID returned as an out parameter from the Commit call when the job was submitted.

You cannot delete an interactive job. Therefore, the parameter Batch applies only when JobID is zero indicating that the job object should be placed in create mode.

Set the ReadOnly parameter to TRUE if you do not want a Console user to be able to delete the job. ReadOnly jobs cannot be altered by the Console, but they can be deleted programmatically through API calls.

This function returns a TRUE if it succeeds, otherwise it returns FALSE.

For an example illustrating the steps for initializing a job object, see CSmpSrvDlg::GetJobObject in the smpsrvdl.cpp file.

JobNotification

Purpose

The Job Scheduling system uses this method to notify your application about job status changes. This interface gets called by the daemon directly.

Syntax

VT_VOID JobNotification(VTS_VARIANT Notification)

Parameters

Notification

VTS_VARIANT

IN

Notification

This contains all the notification information that is returned by the daemon.

Comments

In order to receive messages about job status changes, an application must contain an OLE automation server that exposes a JobNotification method. When the status of a job changes, the Intelligent Agent notifies the Communication Daemon, which calls this interface of the application. If the job is a batch job, the change in job status is also reflected in the Console.

The VOX library provides a class, VoxJobNotifyUnpacker to make the unpacking of the VARIANT passed to the JobNotification interface easy and error-free. Simply declare an object of this class passing the VARIANT to the constructor, and then call any of the following class member functions to access the data. For related information, see VoxJobNotifyUnpacker.

RegisterApplication

Purpose

RegisterApplication is used to flush queued job and event notifications.

Syntax

VT_BOOL RegisterApplication(VTS_BSTR ProgID):

Parameters

ProgID

VTS_BSTR

IN

ProgID

The name of the OLE service which implements the JobNotification API.

Comments

Whenever the OLE service that exposes the JobNotification API is temporarily unavailable, such as when the application is not running, the communication daemon queues its job notifications. In order to retrieve the queued notifications, call the RegisterApplication API. Typically, you will call this API when the application or OLE service initializes.

Note:

You must call RegisterApplication to resend job notifications that have been queued.

SetCredentials

Purpose

SetCredentials is used to set operating systems credentials, username and password, for the job.

Syntax

VT_BOOL SetCredentials(VTS_BSTR Username, VTS_BSTR Password)

Parameters

Username

VTS_BSTR

IN

Password

VTS_BSTR

IN

Username

The username for the job.

Password

The password for the job.

Comments

This function returns a TRUE if it succeeds, otherwise it returns FALSE.

Note:

SetCredentials is optional. If you do not explicitly set the job credentials, the Console submits the job using the preferred credentials specified for the target destination.

For an example illustrating how to use SetCredentials, see CJobCredsDlg::DoSetCredentials in the jobcreds.cpp file.

SetDestinationsEx

Purpose

SetDestinationsEx submits the services or nodes against which the job is to be run and the destination-specific parameters.

Syntax

VT_BOOL SetDestinationsEx(VTS_BSTR DestinationType, 

                VTS_VARIANT Destinations)

Parameters

DestinationType

VTS_BSTR

IN

Destinations

VTS_VARIANT

IN

DestinationType

For information on the types, see Service Types on page -3.

Destinations

A VTS_VARIANT containing a two-dimensional SAFEARRAY of VT_BSTR of the form:

{

{Name1, ParameterList1},

{Name2, ParameterList2},

...

{Namen, ParameterListn}

}

where Namex is a VT_BSTR containing the service or node name and ParameterListx is a VT_BSTR which contains a curly-brace delimited list of arguments. To pass a NULL parameter just use two curly braces that delimit nothing. There can be only one parameter list per destination.

Comments

The destination types are defined in the voxtype.h file. There must be at least one destination. This function returns a TRUE if it succeeds, otherwise it returns FALSE.

For an example illustrating how to use SetDestinationsEx, see CJobDestDlg::DoSetDestinationsEx in the jobcreds.cpp file.

SetJobName

Purpose

SetJobName associates a clear-text name with the job. This text is used by the Console when it displays the job's name.

Syntax

VT_BOOL SetJobName(VTS_BSTR JobName)

Parameters

JobName

VTS_BSTR

IN

JobName

The name by which the Console refers to the job object.

Comments

This function returns a TRUE if it succeeds, otherwise it returns FALSE.

Note:

This function should only be used for batch jobs.

For an example illustrating how to use SetJobName, see CJobNameDlg::DoSetJobName in the jobnamed.cpp file.

SetNotificationObjectProgID

Purpose

SetNotificationObjectProgID is used to submit the name of your application's OLE automation server, so that the Job Scheduling system can send notification information to your application when a job's status changes.

Syntax

VT_BOOL SetNotificationObjectProgID(VTS_BSTR ProgID)

Parameters

ProgID

VTS_BSTR

IN

ProgID

The name of the OLE automation server that will be informed when any status changes occur for the job. The server must be declared to be the active object in order for the communication daemon to locate the JobNotification interface.

Comments

See Job Notification on page -5 for a description of the messages returned when the job state has changed. This function returns a TRUE if it succeeds, otherwise it returns FALSE.

Note:

This call is optional for a batch job. For an example illustrating how to use SetNotificationObjectProgID, see CJobServiceDlg::DoSetNotificationObjectProgID in the jobservi.cpp file.

For related information, see JobNotification.

SetSchedule

Purpose

SetSchedule sets the date, time, and frequency at which to run the job.

Syntax

VT_BOOL SetSchedule(VTS_BSTR Schedule)

Parameters

Schedule

VTS_BSTR

IN

Schedule

The schedule string is divided into several clauses:

• Repeat Frequency
• Start Time
• End Time
• Time Zone Repeat Frequency Clause
  

This clause is mandatory and specifies the frequency with which the job is executed. There are six different repeat modes, specified by the /R keyword. Some modes require a frequency to be specified as well. This is accomplished with the /F or /ON keywords.

All repetitions, except immediate execution, execute initially at the start time and date. If an end time and date are specified, the job ends on the last repetition which occurs before or on that time and date. All times are interpreted relative to the time zone specified.

For those repeat modes which only specify what days an execution is scheduled for, that execution will take place at the time specified by start time of that day. End times need not be specified for such schedules. Multiple repeat clauses can be specified. If this is done, jobs will be executed whenever any of the repeat clauses specify.

.

Table 7-2 Repeat Mode: Immediate

Repeat Mode: Once

Table 7-3 Repeat Mode: Once

Repeat Mode: Every Time Interval

Table 7-4 Repeat Mode: Every Time Interval

Repeat Mode: Every Day Interval

Table 7-5 Repeat Mode: Every Day Interval

Repeat Mode: Every Day of Week Interval

Table 7-6 Repeat Mode: Every Day of Week Interval

Repeat Mode: Every Date of Month

Table 7-7 Repeat Mode: Every Date of Month

Start Time Clause

This clause specifies the start date and start time for the schedule. Inclusion of a start time clause is mandatory for all repeat modes except immediate execution. Time is interpreted relative to the time zone specified.

For those repeat modes which only specify what days an execution is scheduled for, that execution will take place at the time specified by start time of that day.

Table 7-8 Start Time Clause

End Time Clause

This clause specifies the end date and end time for the schedule. Time is interpreted relative to the specified time zone. Use of an end time clause is mandatory for all modes except immediate and one-time execution. Use an end date in the distant future for an indefinite execution. The end time phrase of this clause can be omitted for all but the Every Time Interval Repeat Mode. For those repeat modes which only specify what days an execution is scheduled for, that execution ceases at the time specified by start time of that day if no end time is specified. Otherwise, the execution will cease on the execution scheduled just before the end time and date.

Table 7-9 End Time Clause

Time Zone Clause

This clause is optional and specifies the time zone for which all times should be interpreted. Omission of this clause means that the string should be interpreted relative to the time zone of the host on which the computation is being performed.

Table 7-10 Time Zone Clause

Comments

This function returns a TRUE if it succeeds, otherwise it returns FALSE. This function should only be used for batch jobs. Interactive jobs execute immediately. For an example illustrating how to use SetSchedule, see CJobSchedDlg::DoSetSchedule in the jobsched.cpp file.

SetScript

Purpose

SetScript submits the Tcl script which defines the job, plus a list of the input files for the job.

Syntax

VT_BOOL SetScript(VTS_BSTR ScriptName,

                VTS_VARIANT InputFilenames)

Parameters

ScriptName

VTS_BSTR

IN

InputFilenames

VTS_VARIANT

IN

ScriptName

A fully-qualified path name of a Tcl script.

InputFilenames

A VTS_VARIANT containing a SAFEARRAY of the form:

{

{Filename1}

{Filename2}

...

{Filenamen}

}

where Filenamex is a VT_BSTR containing the fully qualified filenames of the input files.

Comments

This function returns a TRUE if it succeeds, otherwise it returns FALSE. oramsg(orainput), defined for jobs only, is a Tcl list that contains the names of the job's input files. For more information on oramsg, see oramsg Elements on page 9-6.

For an example illustrating how to use SetScript, see CJobScriptDlg::DoSetScript in the jobscrip.cpp file.

VoxJobNotifyUnpacker Class and Methods

The class VoxJobNotifyUnpacker extracts job notification information from the VARIANT vtNotification parameter of the application's JobNotification interface. Call any of the following class member functions to access the data.

• GetDate
• GetError
• GetJobID
• GetNode
• GetOutput
• GetStatus

For an example illustrating how to use VoxJobNotifyUnpacker, see the smpsrdoc.cpp file. For related information, see JobNotification on page 7-10.

GetDate

Purpose

GetDate returns textual representation of time and date of notification.

Syntax

const CString& GetDate() const;

Comments

None.

GetError

Purpose

GetError returns an error code in case of error condition.

Syntax

ULONG GetError() const;

Comments

GetError returns an error code as follows:

VOXJOB_ERROR_QUEUE - queue facility error

VOXJOB_ERROR_FILE - file operation error

VOXJOB_ERROR_MM memory - manager error

VOXJOB_ERROR_TCL - Tcl error

VOXJOB_ERROR_UNIQUE - job name is not unique

VOXJOB_ERROR_JNOTFOUND - job is not found

VOXJOB_ERROR_SNOTFOUND - Tcl script is not found

VOXJOB_ERROR_MANDATORY - mandatory input is missing

VOXJOB_ERROR_MAXLEN - exceeded maximum string length

VOXJOB_ERROR_SCHEDULE - scheduling error

VOXJOB_ERROR_MAXINP - exceeded maximum number of input files

VOXJOB_ERROR_NOUSER - no such user

VOXJOB_ERROR_INTERUPT - outstanding Tcl exists, cannot interrupt

VOXJOB_ERROR_CONNECTION - failed to connect to agent

GetJobID

Purpose

GetJobID returns the ID of job that the notification corresponds to.

Syntax

ULONG GetJobID() const;

Comments

Returns ID of 0 if unpacking of VARIANT failed.

GetNode

Purpose

GetNode returns name of node upon which job was scheduled for execution.

Syntax

const CString& GetNode() const;

Comments

None.

GetOutput

Purpose

GetOutput returns output for notification.

Syntax

const CString& GetOutput() const;

Comments

Only used for notifications with status VOXEXT_JOB_STATUS_COMPLETED, VOXEXT_JOB_STATUS_FAILED, or VOXEXT_JOB_STATUS_INTERMED. In the latter two cases, the output is what would appear as stdout for the Tcl of your job. Intermediate job status output is under user control. See Job Notification Messages on page 7-5.

GetStatus

Purpose

GetStatus returns the status of this notification.

Syntax

ULONG GetStatus() const;

Comments

GetStatus returns the status as follows:

VOXEXT_JOB_STATUS_NONE

VOXEXT_JOB_STATUS_SUBMITTED

VOXEXT_JOB_STATUS_STARTED

VOXEXT_JOB_STATUS_CANCELED

VOXEXT_JOB_STATUS_FAILED

VOXEXT_JOB_STATUS_COMPLETED

VOXEXT_JOB_STATUS_EXPIRED

VOXEXT_JOB_STATUS_INTERMED

Note:

The statuses are listed in the voxext.h file.