6 Job System

What Are Job Executions and Job Runs?

Job executions are usually associated with one target, such as a patch job on a particular database. When a job is run against multiple targets, each execution may execute on one target.

Job executions are not always a one-to-one mapping to a target. Some executions have multiple targets, such as comparing hosts. A few jobs have no target.

When you submit a job to many targets, it would be tedious to examine the status of each execution of the job against each target. For example, suppose you run a patch job against several databases. A typical question would be: Were all the patches successful, and if not, which patches failed? If this patch job runs every week, you would want to know which patches were successful and those that failed each week.

With the Job System, you can easily get these answers by viewing the job run. A job run is the summary of all job executions of a job that ran on a particular scheduled date. For example, if you have a job scheduled for March 5th, you will have a March 5 job run. The job table that shows the job run provides a roll-up of the status of the executions, such as Succeeded, Failed, or Error.

Operations on Job Executions and Job Runs

Besides supporting the standard job operations of create, edit, create like, and delete, the Job System enables you to:

• Suspend jobs —

  You can suspend individual executions or entire jobs. For example, you may need to suspend a job if a needed resource was unavailable, or the job needs to be postponed.

  If a job is scheduled to repeat but is suspended past the scheduled repeat time, the execution of this job would be marked "Skipped."

• Resume jobs —

  After you suspend a job, any scheduled executions do not occur until you decide to resume the job.

• Retry failed executions —

  When analyzing individual executions or entire jobs, it is useful to be able to retry a failed execution after you determine the cause of the problem. This alleviates the need to create a new job for that failed execution. When you use the Retry operation in the Job System, Enterprise Manager provides links from the failed execution to the retried execution and vice versa, should it become useful to retroactively examine the causes of the failed executions. Only the most recent retry is shown in the Job Run page.

With regard to job runs, the Job System enables you to:

• Delete old job runs

• Stop job runs

• Retry job runs

Using Pre-defined Tasks

Enterprise Manager provides predefined job tasks for database targets and deployments. A job task is used to contain predefined, unchangeable logic; for example: patch an application, back up a database, and so forth.

The predefined database jobs include backup, export, import, patch, and clone. These are available from the Availability, Data Movement, and Software and Support property pages you can access from the Database Instance Home page. The predefined jobs associated with deployments include patching, cloning Oracle homes, and cloning databases.

Creating Scripts

In addition to predefined job tasks, you can define your own job tasks by writing code to be included in OS and SQL scripts. The advantages of using these scripts include:

• When defining these jobs, you can use target properties.

• When defining these jobs, you can use the job library, which enables you to share the job and make updates as issues arise. However, you need to resubmit modified library jobs for them to take effect.

• You can submit the jobs against multiple targets.

• You can submit the jobs against a group. The job automatically keeps up with changes to group membership.

• For host command jobs, you can submit to a cluster.

• For SQL jobs, you can submit to a Real Application Cluster.

Sharing Job Responsibilities

To allow you to share job responsibilities, the Job System provides job privileges. These job privileges allow you to share the job with other administrators. Using privileges, you can:

• Grant access to the administrators who need to see the results of the job.

• Grant full access to the administrators who may need to edit the job definition or control the job execution (suspend, resume, stop).

You can grant these privileges on an as-needed basis.

Jobs and Groups

Besides submitting jobs to individual targets, you can submit jobs against a group of targets. Any job that you submit to a group is automatically extended to all its member targets and accounts for the membership of the group as it changes.

For example, if a Human Resources job is submitted to the Payroll group, then a new host is added to this group, the host automatically becomes part of future Human Resources job runs. For instance, for a daily repeating job scheduled for 10:00 a.m. today, if you add a target before that time, the new target would be part of the job run. However, if you add a target after that time today, the target would not be part of today's run, but would be part of the next run. Additionally, if the Payroll group is comprised of diverse targets (for example: databases, hosts, and application servers), the job only runs against applicable targets in the group.

By accessing the Group Home page, you can analyze the job activity for that group.

For information on how to submit a job against a group of targets, see "Specify General Job Information" on on page 6E5.

Selecting a Job Type

Using the Job System, you can create a job by selecting one of the job types, including those below, from the Create Job drop-down in the Job Activity page.

• Block Agent — Blocks an Agent and submits it as a job function. See the discussion below for more information on blocked Agents.

• Clone Home — Copies the known state of an Oracle Home.For example, after you have an Oracle home in a known state (you have chosen particular install options for it, applied required patches to it, and tested it, you may want to clone this Oracle home to one or more hosts.

• Multi-Task — Use to specify primary characteristics for multi-task jobs or corrective actions. Multi-task jobs enable you to create composite jobs by defining tasks, with each task functioning as an independent job. You edit and define tasks in much the same way as a regular job.

  See Section 6.3.4, "Creating a Multi-task Job"for more information.

• OS Command — Runs an operating system command or script.

• SQL Script — Runs a user-defined SQL or PL/SQL script.

Blocked Agents

A blocked Agent is a condition where the OMS rejects all heartbeat or upload requests from the blocked Agent. Therefore, a blocked Agent cannot upload any alerts or metric data to the OMS. However, blocked Agents continue to collect monitoring data.

On a blocked Agent, the OMS "ignores" requests from the blocked Agent, thereby reducing the workload on the OMS. For example, by using this feature for an Agent that fails to upload properly, you can block the Agent until you can resolve the upload issue.

An Agent can become blocked under the following circumstances:

• The system detects that the Agent is no longer sending the correct state. This can occur after a failed recovery, or when users have corrupted state files. The OMS can detect some of the corruptions, and when it finds one, it blocks the Agent until the problem has been resolved.

• A superuser has blocked an Agent to prevent a "rogue" Agent from flooding the system with errors and bad data.

When an Agent is blocked for a long period of time and the Agent is kept running, it eventually must stop monitoring, because it will run out of local disc space to store all of the results. However, this is not an issue, because the "state" of the Agent was corrupt anyway. Therefore, unless corrective actions were taken, the Agent should remain blocked, and no data will then penetrate the system.

Creating an OS Command Job

Use this type of job to run an operating system command or script. Tasks and their dependent steps for creating an OS command are discussed below.

Task 1   Initiate Job Creation

1. From the Enterprise Manager Grid Control Home page, click the Jobs tab. The Job Activity page appears.

2. Select OS Command from the Create Job drop-down, then click Go. The General property page of the Create OS Command Job page appears.

Task 2   Specify General Job Information

Perform these steps on the General property page:

1. Provide a required name for the job, then select a target type from the drop-down.

2. Click Add, then select one or more targets from the Search and Select: Targets pop-up window. The targets now appear in the Targets table. To submit a job against a group of targets, select Group as the Target Type.

   After you have selected a target of a particular type for the job, only targets of that same type can be added to the job. If you change target types, the targets you have populated in the Targets table disappear.

   If you specify a composite (for example, a group or service) as the target for this job, the job executes only against targets in the composite that are of the selected target type. For example, if you specify a target type of host and a group as the target, the job only executes against the hosts in the group, even if there are other non-host targets in the group.

3. Click the Parameters property page link.

Task 3   Specify Parameters

Perform these steps on the Parameters property page:

1. Select either Single Operation or Script from the Command Type drop-down.

   The command or script you specify executes against each target specified in the target list for the job. The Management Agent executes it for each of these targets.

   Depending on your objectives, you can choose one of the following options:

   • Single Operation to run a specific command

   • Script to run an OS script and optionally provide an interpreter, which processes the script; for example, %perlbin%/perl or /bin/sh . The shell scripts size is limited to 2 GB.

     To control the maximum step output size, set the mgmt_job_output_size_limit parameter in MGMT_PARAMETERS to the required limit. Values less than 10 KB and greater than 2 GB are ignored. The default output size is 10 MB.

   Sometimes, a single command line is insufficient to specify the commands to run, and you may not want to install and update a script on all hosts. In this case, you can use the Script option to specify the script text as part of the job.

2. Based on your objectives, follow the instructions in Section 6.3.2.1, "Specifying a Single Operation" and Section 6.3.2.2, "Specifying a Script".

3. Click the Credentials property page link.

Task 4   Specify Credentials - (optional)

On the Credentials property page, you can specify the credentials that you want the Oracle Management Service to use when it runs the OS Command job against target hosts. The job can use either the job submitter's preferred credentials for hosts, or you can specify other credentials to override the preferred credentials.

You do not need to provide input on this page if you have already set preferred credentials. You also do not need to provide input on this page if you are not sharing the job.

• To use preferred credentials:

  1. Select the Use Preferred Credentials radio button.

     If the target for the OS Command job is a database or database group, the host credentials for the database target are used. These are specified on the Database Preferred Credentials page and are different from the host credentials for the host on which the database resides.

     You can set preferred credentials by clicking the Preferences link at the top of the Enterprise Manager console, then clicking the Preferred Credentials link. The Preferred Credentials page appears, where you can click the Set Credentials icon of the target type for which you want to provide credentials.

  2. Select either Normal Host Credentials or Privileged Host Credentials from the Host Credentials drop-down.

     If you select host targets for your job, you can choose to use either Normal or Privileged credentials for the job. You specify these separately on the Preferred Credentials page.

• To override preferred credentials:

  1. Select the Override Preferred Credentials radio button.

     Note that override credentials apply to all targets.

  2. Optionally provide Sudo or PowerBroker details, which must be applicable to all targets. It is assumed that Sudo or PowerBroker settings are already applied on all the hosts on which this job is to run.

     Note:

     You cannot use Sudo or PowerBroker credentials with targets managed by pre-10.2.0.4 Agents or with Windows targets. See your super administrator about setting up these features if they are not currently enabled.

Task 5   Schedule the Job - (optional)

You do not need to provide input on this page if you want to proceed with the system default of running the job immediately after you submit it.

1. Select the type of schedule:

   • One Time (Immediately)

     If you do not set a schedule before submitting a job, Enterprise Manager executes the job immediately with an indefinite grace period. You may want to run the job immediately, but specify a definite grace period in case the job is unable to start for various reasons, such as a blackout, for instance.

     A grace period is a period of time that defines the maximum permissible delay when attempting to start a scheduled job. If the job system cannot start the execution within a time period equal to the scheduled time plus grace period, it sets the job status to Skipped.

   • One Time (Later)

     You can set up a custom schedule to execute the job at a designated time in the future. When you set the Time Zone for your schedule, the job runs simultaneously on all targets when this time zone reaches the start time you specify. If you select each target's time zone, the job runs at the scheduled time using the time zone of the managed targets. The time zone you select is used consistently when displaying date and time information about the job, such as on the Job Activity page, Job Run page, and Job Execution page.

     For example, if you have targets in the Western United States (US Pacific Time) and Eastern United States (US Eastern Time), and you specify a schedule where Time Zone = US Pacific Time and Start Time = 5:00 p.m., the job runs simultaneously at 5:00 p.m. against the targets in the Western United States and at 8:00 p.m. against the targets in the Eastern United States. If you specify 5:00 p.m. in the Agent time zone, the executions do not run concurrently. The EST target would run 3 hours earlier.

   • Repeating

     Specify the Frequency Type (time unit) and Repeat Every (repeat interval) parameters to define your job's repeat interval. The Repeat Until options are as follows:

     • Indefinite — Select to allow your job to continue running indefinitely. Otherwise, select Specified Date.

     • Specified Date — Set the date for your job to stop running, and set the time for the stop date you specified.

     Note that both the end date and time determine the last execution. For example, for a job that runs daily at 6 p.m., where...

     Start Time is June 1, 2010 at 6 p.m. End Time is June 30, 2010 at 4 a.m.

     ... the last execution runs on June 29, not June 30, since the June 30 end time occurs before the daily time of the job.

2. Specify the Grace Period.

   The grace period controls the latest start time for the job in case the job is delayed. A job might not start for many reasons, but the most common reasons are that the Agent was down or there was a blackout. By default, jobs are scheduled with indefinite grace periods.

   If the job starts on time, the grace period is ignored. For example, a job scheduled for 1 p.m. with a grace period of 1 hour does not run if the job does not start before 2 p.m.

3. Click the Access property page link.

Task 6   Specify Who Can Access the Job - (optional)

You do not need to provide input for this page if you do not want to share the job. The table shows the access that administrators and roles have to the job. Only the job owner (or Super Administrator) can make changes on the Job Access page.

1. Optional: Change access levels for administrators and roles, or remove administrators and roles. Your ability to make changes depends on your function.

   If you are a job owner, you can:

   • Change the access of an administrator or role by choosing the Full or View access right in the Access Level column in the table.

   • Remove all access to the job for an administrator or role by clicking the icon in the Remove column for the administrator or role. All administrators with Super Administrator privileges have the View access right to a job. If you choose to provide access rights to a role, you can only provide the View access right to the role, not the Full access right.

   If you are a Super Administrator, you can:

   • Grant VIEW access to other Enterprise Manager administrators or roles.

   • Revoke all administrator access privileges.

   For more information on access levels, see Section 6.3.2.3, "Access Level Rules".

2. Optional: Click Add to add administrators and roles. The Create Job Add Administrators and Roles page appears.

   1. Specify a Name and Type in the Search section and click Go. If you just click Go without specifying a Name or Type, all administrators and roles in the Management Repository appear in the table.

      The value you specify in the Name field is not case-sensitive. You can specify either * or % as a wildcard character at any location in a string (the wildcard character is implicitly added to the end of any string). For example, if you specify %na in the Name field, names such as ANA, ANA2, and CHRISTINA may be returned as search results in the Results section.

   2. Select one or more administrators or roles in the Results section, then click Select to grant them access to the job. Enterprise Manager returns to the Create Job Access page or the Edit Job Access page, where you can modify the access of administrators and roles.

3. Optional: Define a notification rule.

   You can use the Notification system (rule creation) to easily associate specific jobs with a notification rule. The Grid Control Notification system enables you to define a notification rule that sends e-mail to the job owner when a job enters one of these chosen states:

   • Scheduled

   • Running

   • Suspended

   • Succeeded

   • Problems

   • Action Required

   Note:

   Before you can specify notifications, you need to set up your email account and notification preferences. See Chapter 3, "Notifications" for this information.

Task 7   Concluding Job Creation

At this point, you can either submit the job for execution or save it to the job library.

• Submitting the job —

  Click Submit to send the active job to the job system for execution, and then view the job's execution status on the main Job Activity page. If you are creating a library job, Submit saves the job to the library and returns you to the main Job Library page where you can edit or create other library jobs.

  If you submit a job that has problems, such as missing parameters or credentials, an error appears and you will need to correct these issues before submitting an active job. For library jobs, incomplete specifications are allowed, so no error occurs.

  Note:

  If you click Submit without changing the access, only Super Administrators can view your job.

• Saving the job to the library —

  Click Save to Library to the job to the Job Library as a repository for frequently used jobs. Other administrators can then share and reuse your library job if you provide them with access rights. Analogous to active jobs, you can grant View or Full access to specific administrators. Additionally, you can use the job library to store:

  • Basic definitions of jobs, then add targets and other custom settings before submitting the job

  • Jobs for your own reuse or to share with others. You can share jobs using views or giving full access to the jobs.

  • Critical jobs for resubmitting later, or revised versions of these jobs as issues arise

/bin/df -k /private

Creating a SQL Script Job

The basic process for creating a SQL script job is the same as described in Section 6.3.2, "Creating an OS Command Job." The following sections provide supplemental information specific to script jobs.

WHENEVER SQLERROR EXIT SQL.SQLCODE
select column_does_not_exist from dual;

-- SQL*Plus will NOT return an error for the next SELECT statement
SELECT COLUMN_DOES_NOT_EXIST FROM DUAL;
 
WHENEVER SQLERROR EXIT SQL.SQLCODE;
BEGIN
  -- SQL*Plus will return an error at this point
  SELECT COLUMN_DOES_NOT_EXIST FROM DUAL;
END;
/
WHENEVER SQLERROR CONTINUE;

variable exit_code number;
 
BEGIN
 DECLARE
 local_empno number(5);
 BEGIN
  -- do some work which will raise exception: no_data_found
  SELECT 123 INTO local_empno FROM sys.dual WHERE 1=2;
 EXCEPTION
  WHEN no_data_found THEN
    :exit_code := 10;
  WHEN others THEN
    :exit_code := 2;
  END;
 END;
/
exit :exit_code;

-- interactive mode only
 
col test new_value bye
SELECT 123 test
FROM dual;
exit &bye;

Creating a Multi-task Job

The basic process for creating a multi-task job is the same as described in Section 6.3.2, "Creating an OS Command Job." The following sections provide supplemental information specific to multi-task jobs.