Oracle Enterprise Manager Application Developer's Guide Release 1.4.0 A53701_01 |
|
This chapter covers the Job Scheduling system Interface. It describes:
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.
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.
Unless it is read-only, an externally-submitted batch job can be deleted from the Console.
To submit a batch job:
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.
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.
SetScript
to submit the name of the script for the job. See SetScript on page 7-19.
SetJobName
to provide a clear-text name for the Console to display when referring to the job. See SetJobName on page 7-13.
SetSchedule
to set the job schedule. See SetSchedule on page 7-15.
SetNotificationObjectProgID
to submit the class name of the OLE automation server to receive notifications about the job (optional). See SetNotificationObjectProgID on page 7-14.
SetCredentials
to specify the host username and password for the job. See SetCredentials on page 7-11.
JobID
if you plan to coordinate job notifications. See Commit on page 7-8.
SetNotificationObjectProgID
was called.
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:
JobID
to zero, and Batch
and ReadOnly
to FALSE in the call to Initialize
.
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.
SetScript
to submit the fully qualified name of the script. See SetScript on page 7-19.
SetNotificationObjectProgID
to submit the name of the OLE automation server to receive notifications about the job. See SetNotificationObjectProgID on page 7-14.
SetNotificationObjectProgID
is required for interactive jobs.
SetCredentials
(optional) to submit the username and password to be used for the job. See SetCredentials on page 7-11.
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.
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.
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:
JobID
to the ID of the job you want to delete and Batch
to TRUE in the call to Initialize
.
DeleteJob
to delete a job.
Interactive jobs cannot be deleted.
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.
Use the helper function VoxJobNotifyUnpacker
to extract all the information from the VARIANT passed to your application's JobNotification
method.
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.
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.
When you submit a job, you will receive one of the following notifications:
When a job initiates, you will receive a VOXEXT_JOB_STATUS_STARTED
notification. Next you will receive one of the following notifications:
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.
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:
Variable | Meaning |
---|---|
$SMP_USER |
user name of job credential |
$SMP_PASSWORD |
password of job credential |
$SMP_SERVICE |
service name of job destination |
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.
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.
The following section describes the external interface calls for the Job Scheduling system.
Commit
causes the job object to schedule the job.
VT_BOOL Commit(VTS_PI4 pJobID)
Name | Type | Mode |
---|---|---|
pJobID |
VTS_PI4 |
IN/OUT |
The unique identifier for a job.
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
allows for the deletion and the removal of the job from the remote nodes schedule.
VT_BOOL DeleteJob()
None
Interactive jobs cannot be deleted. This function returns a TRUE if it succeeds, otherwise it returns FALSE.
Initialize
must be called before DeleteJob
.
Initialize
initializes a newly-created a job object.
VT_BOOL Initialize(VTS_I4 JobID,
VTS_BOOL Batch,
VTS_BOOL ReadOnly)
Name | Type | Mode |
---|---|---|
JobID |
VTS_I4 |
IN |
Batch |
VTS_BOOL |
IN |
ReadOnly |
VTS_BOOL |
IN |
The unique identifier for a job. Set to zero to create a new job.
Indicates whether the job is an interactive or batch job. This parameter only applies if JobID
is zero.
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.
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.
The Job Scheduling system uses this method to notify your application about job status changes. This interface gets called by the daemon directly.
VT_VOID JobNotification(VTS_VARIANT Notification)
Name | Type | Mode |
---|---|---|
Notification |
VTS_VARIANT |
IN |
This contains all the notification information that is returned by the daemon.
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
is used to flush queued job and event notifications.
VT_BOOL RegisterApplication(VTS_BSTR ProgID):
Name | Type | Mode |
---|---|---|
ProgID |
VTS_BSTR |
IN |
The name of the OLE service which implements the JobNotification
API.
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.
You must call RegisterApplication
to resend job notifications that have been queued.
SetCredentials
is used to set operating systems credentials, username and password, for the job.
VT_BOOL SetCredentials(VTS_BSTR Username, VTS_BSTR Password)
Name | Type | Mode |
---|---|---|
Username |
VTS_BSTR |
IN |
Password |
VTS_BSTR |
IN |
The username for the job.
The password for the job.
This function returns a TRUE if it succeeds, otherwise it returns FALSE.
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
submits the services or nodes against which the job is to be run and the destination-specific parameters.
VT_BOOL SetDestinationsEx(VTS_BSTR DestinationType,
VTS_VARIANT Destinations)
Name | Type | Mode |
---|---|---|
DestinationType |
VTS_BSTR |
IN |
Destinations |
VTS_VARIANT |
IN |
For information on the types, see Service Types on page -3.
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.
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
associates a clear-text name with the job. This text is used by the Console when it displays the job's name.
VT_BOOL SetJobName(VTS_BSTR JobName)
Name | Type | Mode |
---|---|---|
JobName |
VTS_BSTR |
IN |
The name by which the Console refers to the job object.
This function returns a TRUE if it succeeds, otherwise it returns FALSE.
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
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.
VT_BOOL SetNotificationObjectProgID(VTS_BSTR ProgID)
Name | Type | Mode |
---|---|---|
ProgID |
VTS_BSTR |
IN |
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.
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.
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
sets the date, time, and frequency at which to run the job.
VT_BOOL SetSchedule(VTS_BSTR Schedule)
Name | Type | Mode |
---|---|---|
Schedule |
VTS_BSTR |
IN |
The schedule
string is divided into several clauses:
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.
.
Format | Interpretation | Examples |
---|---|---|
/R=I |
Execute immediately. |
/R=I |
Repeat Mode: Once
Format | Interpretation | Examples |
---|---|---|
/R=O |
Execute once at start date and time. |
/R=O |
Repeat Mode: Every Time Interval
Format | Interpretation | Examples |
---|---|---|
/R=H /F=HH:MM:SS |
Execute repeatedly every specified interval. All fields must be specified. |
/R=H /F=02:30:00 |
Repeat Mode: Every Day Interval
Format | Interpretation | Examples |
---|---|---|
/R=D /F=<# of days> |
Execute once every specified number of days. |
/R=D /F=2 |
Repeat Mode: Every Day of Week Interval
Repeat Mode: Every Date of Month
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.
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.
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.
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
submits the Tcl script which defines the job, plus a list of the input files for the job.
VT_BOOL SetScript(VTS_BSTR ScriptName,
VTS_VARIANT InputFilenames)
Name | Type | Mode |
---|---|---|
ScriptName |
VTS_BSTR |
IN |
InputFilenames |
VTS_VARIANT |
IN |
A fully-qualified path name of a Tcl script.
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.
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.
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.
For an example illustrating how to use VoxJobNotifyUnpacker
, see the smpsrdoc.cpp
file. For related information, see JobNotification on page 7-10.
GetDate
returns textual representation of time and date of notification.
const CString& GetDate() const;
None.
GetError
returns an error code in case of error condition.
ULONG GetError() const;
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
returns the ID of job that the notification corresponds to.
ULONG GetJobID() const;
Returns ID of 0 if unpacking of VARIANT failed.
GetNode
returns name of node upon which job was scheduled for execution.
const CString& GetNode() const;
None.
GetOutput
returns output for notification.
const CString& GetOutput() const;
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
returns the status of this notification.
ULONG GetStatus() const;
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
The statuses are listed in the voxext.h
file.