Scheduler Enhancements

Oracle Database 11g: New Features for Administrators B - 2 Objectives After completing this lesson, you should be able to: Use lightweight jobs Use Scheduler email notification Create a file watcher Create remote database jobs Create multiple destination jobs Oracle Database 11g: New Features for Administrators B - 2

Oracle Database 11g: New Features for Administrators B - 3 Lightweight Jobs Persistent lightweight jobs: Created from a job template Recoverable JOB_STYLE => LIGHTWEIGHT Lightweight Jobs Some customers need to create hundreds of jobs each second. With regular jobs, each job creates a database object describing the job, modifying several tables, and creating redo in the process. In the Oracle Database 11g Scheduler, there is a persistent lightweight job. The goal of a lightweight job is to reduce the overhead and the time required to start a job. A minimal amount of metadata is created for the job. This reduces the time required and the redo created when the job starts. To achieve these goals, the lightweight job has a small footprint on disk for the job metadata and for storing run-time data. The footprint on disk also makes recovery and load balancing possible in RAC environments. The lightweight job is always created from a job template, which can be a stored procedure or a program. The stored procedure holds all the information needed for the job. A few job attributes may be set (such as job arguments). Job templates are created by using the DBMS_SCHEDULER.CREATE_PROGRAM procedures. Oracle Database 11g continues to support the database object–based jobs that have existed since Oracle Scheduler was first introduced in Oracle 10g. Lightweight jobs are not intended to replace these jobs because each job type has its own advantages and gives you the flexibility to choose a job based on your needs. Oracle Database 11g: New Features for Administrators B - 3

Oracle Database 11g: New Features for Administrators B - 4 Choosing the Right Job Regular job Highest overhead Best recovery Most flexible Persistent lightweight job Less overhead Some recovery Limited change to attributes Choosing the Right Job The advantages and disadvantages of the types of jobs are as follows: A regular job offers maximum flexibility but entails a significant overhead in create/drop performance. A job can be created with a single command. Users have fine-grained control of privileges on the job and can also use programs or stored procedures owned by other users. A regular job requires the job database object to be created and dropped. This action updates several tables and the associated redo. Users who are creating a relatively small number of jobs that run relatively infrequently should choose regular jobs. A persistent lightweight job has a significant improvement in create/drop time because it does not have the overhead of creating a database object. Every lightweight job is created from a job template, which is stored as a program. Because persistent lightweight jobs write state information to disk at run time, only a small improvement is expected in execution. There are several limitations to persistent lightweight jobs: Users cannot set privileges on these jobs. Instead, they inherit their privileges from the parent job template. The use of a template is mandatory. It is not possible to create a fully self-contained persistent lightweight job. Only certain job attributes are available to be set, such as JOB_ARGUMENTS. Lightweight jobs are most useful when the user needs to create a large number of jobs in a very short time (from 10 to 100 jobs a second) and has a library of programs (job templates) available for use. Oracle Database 11g: New Features for Administrators B - 4

Scheduler Email Notification: Overview 11.2 Scheduler Email Notification: Overview Jobs can be configured so that email notifications are sent when the job changes state. Email messages can be triggered by any event in a list of specified job state events, such as when a job fails. More than one email notification can be configured for a job. An email message can be sent to multiple recipients. Scheduler Email Notification: Overview The job email notification feature enables you to add email notifications to existing jobs so that events of interest that happen to the job are emailed to specified email addresses. For each job, you can add notifications for different events. You can send the email notification to more than one recipient. Oracle Database 11g: New Features for Administrators B - 5

Using Scheduler Email Notification 11.2 Using Scheduler Email Notification To use Scheduler email notification, perform the following configuration steps on each database: Set the Scheduler email_server attribute to the address of the SMTP server you will use to send email message. Optionally, set the Scheduler email_sender attribute to a default sender email address. For each job for which you want the system to send email messages, perform the following: Use the DBMS_SCHEDULER.ADD_JOB_EMAIL_NOTIFICATION procedure to add email notifications for a specified job. Using Scheduler Email Notification To enable the email notification feature, perform the following one-time configuration steps on each database: Set the email_server Scheduler attribute. Optionally, you can use the email_sender Scheduler attribute to specify a default sender email address for the email notifications. After creating a job, execute the DBMS_SCHEDULER.ADD_JOB_EMAIL_NOTIFICATION procedure to add one or more notifications for the job. Additional information is provided on the following pages. Oracle Database 11g: New Features for Administrators B - 6

Setting the email_server Attribute 11.2 Setting the email_server Attribute Specify an SMTP server address that the Scheduler will use to send email notifications for job state events: DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE ('email_server','host[:port]'); Setting the email_server Attribute The Scheduler email_server attribute specifies an SMTP server address that the Scheduler uses to send email notifications for job state events. The format for the attribute is host[:port] where host is the host name or IP address of the SMTP server, and port is the TCP port on which the SMTP server listens. If port is not specified, a default port of 25 is used. If you do not set the email_server attribute, set it to NULL, or set it to an invalid SMTP server address, the Scheduler cannot send job state email notifications. SMTP servers that require secure sockets layer (SSL) connections or require user authentication are not supported. Oracle Database 11g: New Features for Administrators B - 7

Setting the email_sender Attribute 11.2 Setting the email_sender Attribute Specify a default email address of the sender for job state email notifications: DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE ('email_sender','valid email address'); Setting the email_sender Attribute You can use the email_sender attribute to specify a default email address of the sender for job state email notifications. The email address specified must be valid. If you do not set this attribute or set it to NULL, job state email notifications that do not specify a sender address will not have a FROM address in the email header. Oracle Database 11g: New Features for Administrators B - 8

Using ADD_JOB_EMAIL_NOTIFICATION 11.2 Using ADD_JOB_EMAIL_NOTIFICATION DBMS_SCHEDULER.ADD_JOB_EMAIL_NOTIFICATION ( job_name IN VARCHAR2, recipients IN VARCHAR2, sender IN VARCHAR2 DEFAULT NULL, subject IN VARCHAR2 DEFAULT dbms_scheduler.default_notification_subject, body IN VARCHAR2 DEFAULT dbms_scheduler.default_notification_body, events IN VARCHAR2 DEFAULT 'JOB_FAILED,JOB_BROKEN,JOB_SCH_LIM_REACHED, JOB_CHAIN_STALLED,JOB_OVER_MAX_DUR', filter_condition IN VARCHAR2 DEFAULT NULL); Using ADD_JOB_EMAIL_NOTIFICATION The DBMS_SCHEDULER.ADD_JOB_EMAIL_NOTIFICATION procedure adds one or more job email notifications. Email messages will be sent to the specified recipient addresses whenever any of the listed events are generated by the job. The job is automatically modified to raise these events. If a filter condition is specified, only events that match the specification in FILTER_CONDITION will generate an email message. This procedure will fail if the EMAIL_SERVER scheduler attribute is not set or if the specified job does not exist. Note: The user calling this procedure must be the owner of the job, have the CREATE ANY JOB system privilege, or have been granted the ALTER privilege for the job. Procedure arguments are as follows: JOB_NAME: Name of the job for which email notifications will be sent. The value cannot be NULL. RECIPIENTS: Comma-separated list of email addresses to send notifications to. Email notifications will be sent to all specified email addresses. The value cannot be NULL. SENDER: Email address to use as the sender for email notifications. If NULL, the value of the DEFAULT_EMAIL_SENDER scheduler attribute (if it is a valid email address) will be used. Oracle Database 11g: New Features for Administrators B - 9

Using REMOVE_JOB_EMAIL_NOTIFICATION 11.2 Using REMOVE_JOB_EMAIL_NOTIFICATION DBMS_SCHEDULER.REMOVE_JOB_EMAIL_NOTIFICATION ( job_name IN VARCHAR2, recipients IN VARCHAR2 DEFAULT NULL, events IN VARCHAR2 DEFAULT NULL); Using REMOVE_JOB_EMAIL_NOTIFICATION The DBMS_SCHEDULER.REMOVE_JOB_EMAIL_NOTIFICATION procedure is used to remove one or more email notifications for the specified job. Note: The user calling this procedure must be the owner of the job, have the CREATE ANY JOB system privilege, or have been granted the ALTER privilege for the job. Procedure arguments are as follows: JOB_NAME: Name of the job for which email notifications will be removed; cannot be NULL RECIPIENTS: Comma-separated list of email addresses to remove notifications for. If the value is NULL, all notifications for the given job and specified events will be removed. EVENTS: Comma-separated list of events for which to remove email notifications. If the value is NULL, all notifications for the given job and the specified email addresses will be removed. Oracle Database 11g: New Features for Administrators B - 11

Email Notification: New Dictionary Views 11.2 Email Notification: New Dictionary Views Query the following views to determine what email notifications have been set: DBA_SCHEDULER_NOTIFICATIONS ALL_SCHEDULER_FILE_NOTIFICATIONS USER_SCHEDULER_FILE_NOTIFICATIONS Email Notification: New Dictionary Views There are three new views with email notification information: DBA_SCHEDULER_NOTIFICATIONS, ALL_SCHEDULER_NOTIFICATIONS, and USER_SCHEDULER_NOTIFICATIONS. The DBA_SCHEDULER_NOTIFICATIONS and ALL_SCHEDULER_NOTIFICATIONS views have the following columns (the USER_ view does not have an OWNER column): OWNER: Owner of the job the notification is for JOB_NAME: Name of the job the notification is for JOB_SUBNAME: Subname of the job the notification is for RECIPIENT: Email address to send this email notification to SENDER: Email address to send this email notification from SUBJECT: Subject of the email notification BODY: Body of the email notification FILTER_CONDITION: Filter specifying which job events to send emails for EVENT: Job event to send emails for EVENT_FLAG: Event number of the job event to send emails for Oracle Database 11g: New Features for Administrators B - 12

Scheduler File Watcher: Overview 11.2 Scheduler File Watcher: Overview Scheduler has a built-in functionality that enables it to “watch” for files on the local system or on a remote system. Scheduler raises an event that can be picked by event-based jobs when it detects that the “watched” file has arrived. The file watcher can be referenced by either event-based jobs or schedules. The file watching functionality on remote machines is handled through the Scheduler agent. Scheduler File Watcher: Overview A file watcher is a database object used to define the location, name, and other properties of a file. When the file arrives on a system, the Scheduler starts a job. You create the file watcher object by using the DBMS_SCHEDULER.CREATE_FILE_WATCHER procedure, and then create any number of event-based jobs or event schedules that reference the file watcher. When the file watcher detects the arrival of the specified file, it raises a file arrival event. The job started by the file arrival event can retrieve the event message to obtain information about the newly arrived file. A file watcher can watch for a file on the local system (the server running Oracle Database) or a remote system that is running the Scheduler agent. Oracle Database 11g: New Features for Administrators B - 13

Creating a File Watcher and an Event-Based Job 11.2 Creating a File Watcher and an Event-Based Job To create a file watcher and create the event-based job that starts when the designated file arrives, perform the following tasks: 1. Create a Scheduler credential object (a credential) with which to authenticate with the host operating system for access to the file. 2. Create a file watcher. 3. Create a Scheduler program object with a metadata argument that references the event message. 4. Create an event-based job that references the file watcher. 5. Enable the file watcher, the program, and the job. Creating a File Watcher and an Event-Based Job You can perform the tasks listed in the slide to create a file watcher and the event-based job that starts when the specified file arrives. The steps are discussed in more detail on the following pages. Oracle Database 11g: New Features for Administrators B - 14

Step 1: Creating a Scheduler Credential Object 11.2 Step 1: Creating a Scheduler Credential Object Create a credential for the operating system user that requires access to the watched-for file: Grant EXECUTE on the credential to the schema that owns the event-based job that the file watcher will start: BEGIN DBMS_SCHEDULER.CREATE_CREDENTIAL('', '', ''); END; GRANT EXECUTE ON credential_name to user_name; Step 1: Creating a Scheduler Credential Object The file watcher requires a Scheduler credential object (a credential) with which to authenticate with the host operating system for access to the file. Note: EXECUTE on the credential does not need to be granted when the event-based job and the credential reside in the same schema. Oracle Database 11g: New Features for Administrators B - 15

Step 2: Creating a File Watcher 11.2 Step 2: Creating a File Watcher Create the file watcher: Grant EXECUTE on the file watcher to any schema that owns an event-based job that references the file watcher: BEGIN DBMS_SCHEDULER.CREATE_FILE_WATCHER( FILE_WATCHER_NAME => '', DESTINATION =>, DIRECTORY_PATH => '', FILE_NAME => '', CREDENTIAL_NAME => '', ENABLED => ); END; Step 2: Creating a File Watcher Create the file watcher by using the DBMS_SCHEDULER.CREATE_FILE_WATCHER procedure. Additional information is provided on the next page. Note: EXECUTE on the file watcher does not need to be granted when the event-based job and the file watcher reside in the same schema. GRANT EXECUTE ON file_watcher_name to user_name; Oracle Database 11g: New Features for Administrators B - 16

Using DBMS_SCHEDULER.CREATE_FILE_WATCHER 11.2 Using DBMS_SCHEDULER.CREATE_FILE_WATCHER Argument Data type Default FILE_WATCHER_NAME VARCHAR2 No default DESTINATION NULL DIRECTORY_PATH FILE_NAME CREDENTIAL_NAME MIN_FILE_SIZE PLS_INTEGER STEADY_STATE_DURATION INTERVAL DAY TO SECOND COMMENTS ENABLED BOOLEAN TRUE Using DBMS_SCHEDULER.CREATE_FILE_WATCHER You create a database object called a file watcher by using the DBMS_SCHEDULER.CREATE_FILE_WATCHER procedure. It has the following arguments: FILE_WATCHER_NAME: Name of the file watcher DESTINATION: Remote destination at which the file will arrive. If NULL, the destination is the local machine. DIRECTORY_PATH: Directory in which file will be located. A single wildcard '?' is permitted at the beginning of the path name and it will denote the value of ORACLE_HOME. The value cannot be NULL. FILE_NAME: Name of the file that is being "watched." Two wildcards are permitted, '?' (any single character) and '*' (any sequence of 0 or more characters). The value cannot be NULL. CREDENTIAL_NAME: Name of a valid credential object. File watcher owner should have execute privileges on this object if the create call is to succeed. The value cannot be NULL. MIN_FILE_SIZE: Minimum size the file should be before the file watcher will report that it is found; cannot be NULL. STEADY_STATE_DURATION: Minimum interval of time the file should stay unchanged before the file watcher will report that it is found. If this is NULL, an internal default value will be used. COMMENTS: Comments on this file watcher ENABLED: Whether this file watcher is enabled Oracle Database 11g: New Features for Administrators B - 17

Step 3: Creating a Scheduler Program Object 11.2 Step 3: Creating a Scheduler Program Object Create the program: BEGIN DBMS_SCHEDULER.CREATE_PROGRAM( PROGRAM_NAME => '', PROGRAM_TYPE => 'STORED_PROCEDURE', PROGRAM_ACTION => '', NUMBER_OF_ARGUMENTS => 1, ENABLED => FALSE); END; Step 3: Creating a Scheduler Program Object Create a Scheduler program object with a metadata argument that references the event message. Oracle Database 11g: New Features for Administrators B - 18

Step 3: Creating a Scheduler Program Object 11.2 Step 3: Creating a Scheduler Program Object Define the metadata argument using the EVENT_MESSAGE attribute: Create the stored procedure with an argument of type SYS.SCHEDULER_FILEWATCHER_RESULT that the program invokes. BEGIN DBMS_SCHEDULER.DEFINE_METADATA_ARGUMENT( PROGRAM_NAME => '', METADATA_ATTRIBUTE => 'event_message', ARGUMENT_POSITION => 1); END; Step 3: Creating a Scheduler Program Object (continued) Then create a stored procedure that the program invokes. The stored procedure must have an argument of type SYS.SCHEDULER_FILEWATCHER_RESULT, which is the data type of the event message. The position of that argument must match the position of the defined metadata argument. The procedure can access attributes of this abstract data type to learn about the arrived file. Additional information about SYS.SCHEDULER_FILEWATCHER_RESULT is provided on the next page. Oracle Database 11g: New Features for Administrators B - 19

Using the SCHEDULER_FILEWATCHER_RESULT Object Type 11.2 Using the SCHEDULER_FILEWATCHER_RESULT Object Type Argument Data type Definition DESTINATION VARCHAR2(4000) Destination at which the file was found DIRECTORY_PATH Directory in which the file was found ACTUAL_FILE_NAME Actual name of the file FILE_SIZE NUMBER Size of the file FILE_TIMESTAMP TIMESTAMP WITH TIME ZONE Timestamp of the file TS_MS_FROM_EPOCH For internal use only MATCHING_REQUESTS SCHEDULER_FILEWATCHER_REQ_LIST Defined as a table of SCHEDULER_FILEWATCHER_REQUEST Using the SCHEDULER_FILEWATCHER_RESULT Object Type SCHEDULER_FILEWATCHER_RESULT is the data type of a file arrival event message. You access the event message as a parameter of an event-based job (or a parameter of a program referenced by an event-based job). The message contains information needed to locate and process a file that arrived on a local or remote system. Oracle Database 11g: New Features for Administrators B - 20

Using the SCHEDULER_FILEWATCHER_REQUEST Object Type 11.2 Using the SCHEDULER_FILEWATCHER_REQUEST Object Type Argument Data type Definition OWNER VARCHAR2(4000) File watcher owner NAME File watcher name REQUESTED_PATH_NAME Requested path name REQUESTED_FILE_NAME Requested file name CREDENTIAL_OWNER Owner of used credential CREDENTIAL_NAME Credential name MIN_FILE_SIZE NUMBER Minimum file size STEADY_STATE_DUR Steady state duration Using the SCHEDULER_FILEWATCHER_REQUEST Object Type The SCHEDULER_FILEWATCH_REQUEST object is returned in the MATCHING_REQUESTS attribute of the SCHEDULER_FILEWATCHER_RESULT object type. Oracle Database 11g: New Features for Administrators B - 21

Step 4: Creating an Event-Based Job that References the File Watcher 11.2 Step 4: Creating an Event-Based Job that References the File Watcher Create the job: BEGIN DBMS_SCHEDULER.CREATE_JOB( JOB_NAME => '', PROGRAM_NAME => '', EVENT_CONDITION => NULL, QUEUE_SPEC => '<name_of_file_watcher>', AUTO_DROP => FALSE, ENABLED => FALSE); END; Optionally, enable the job to run for each instance of the file arrival event: Step 4: Creating an Event-Based Job that References the File Watcher You can use the DBMS_SCHEDULER.SET_ATTRIBUTE procedure to enable the job to run for each instance of the file arrival event, even if the job is already processing a previous event. Set the PARALLEL_INSTANCES attribute to TRUE. This enables the job to run as a lightweight job so that multiple instances of the job can be started quickly. If PARALLEL_INSTANCES is set to the default value of FALSE, file watcher events that occur while the event-based job is already processing another will be discarded. BEGIN DBMS_SCHEDULER.SET_ATTRIBUTE('','PARALLEL_INSTANCES', TRUE); END; Oracle Database 11g: New Features for Administrators B - 22

Step 5: Enabling the Objects 11.2 Step 5: Enabling the Objects Enable the file watcher, the program, and the job: BEGIN DBMS_SCHEDULER.ENABLE('MY_FILE_WATCHER, DSSUSER.MY_PROGRAM, DSSUSER.MY_JOB'); END; Step 5: Enabling the Objects Use the DBMS_SCHEDULER.ENABLE procedures to enable the file watcher, the program, and the job. Oracle Database 11g: New Features for Administrators B - 23

Enabling File Arrival Events from Remote Systems 11.2 Enabling File Arrival Events from Remote Systems Perform the following tasks to enable the raising of file arrival events at remote systems: 1. Set up the database to run remote external jobs. 2. Install, configure, register, and start the Scheduler agent on the first remote system. 3. Repeat step 2 for each additional remote system. Enabling File Arrival Events from Remote Systems To receive file arrival events from a remote system, you must install the Scheduler agent on that system, and you must register the agent with the database. The remote system does not need an Oracle Database instance to generate file arrival events. Refer to the Oracle Database Administrator's Guide 11g Release 2 for detailed information. Oracle Database 11g: New Features for Administrators B - 24

Using DBMS_SCHEDULER.DROP_FILE_WATCHER 11.2 Using DBMS_SCHEDULER.DROP_FILE_WATCHER Argument Data type Default FILE_WATCHER_NAME VARCHAR2 No default FORCE BOOLEAN FALSE Using DBMS_SCHEDULER.DROP_FILE_WATCHER You can drop the file watcher database object by using the DBMS_SCHEDULER.DROP_FILE_WATCHER procedure. It has the following arguments: FILE_WATCHER_NAME: Name of the file watcher FORCE: Force flag. When set to FALSE, the file watcher will not be dropped if there are any jobs that depend on it. When set to TRUE, jobs that reference the dropped file watcher are disabled. If there are executing jobs referencing the file watcher when you drop the file watcher, they are not affected by this procedure and continue to execute. Oracle Database 11g: New Features for Administrators B - 25

File Watcher: Changes to Existing DBMS_SCHEDULER Procedures 11.2 File Watcher: Changes to Existing DBMS_SCHEDULER Procedures CREATE_JOB and CREATE_JOBS: QUEUE_SPEC argument can be a file watcher name. CREATE_EVENT_SCHEDULE: QUEUE_SPEC argument can be a file watcher name. SET_ATTRIBUTE and GET_ATTRIBUTE: These can be used to set and get individual attributes of a file watcher. ENABLE and DISABLE: These can accept a file watcher name as an argument. File Watcher: Changes to Existing DBMS_SCHEDULER Procedures CREATE_JOB and CREATE_JOBS: The QUEUE_SPEC argument to these calls can be a file watcher name instead of a queue name. The job created will be an event-based job whose source queue is the one in which the file watcher will enqueue its results. Do not specify an agent name with the file watcher. CREATE_EVENT_SCHEDULE: The QUEUE_SPEC argument to this call can be a file watcher name instead of a queue name. The schedule created will be an event-based schedule whose source queue is the one in which the file watcher will enqueue its results. Do not specify an agent name with the file watcher. SET_ATTRIBUTE and GET_ATTRIBUTE: These two calls can accept a file watcher name as argument. For a file watcher, the following attributes are legal: DESTINATION, DIRECTORY_PATH, FILE_NAME, CREDENTIAL_NAME, MIN_FILE_SIZE. STEADY_STATE_DURATION and COMMENTS. ENABLE and DISABLE: These two calls can accept a file watcher name as an argument. A file watcher will not be enabled unless all of its attributes have been set to legal values and the file watcher owner has execute privileges on the credential being used. If a file watcher is disabled with the force flag set to FALSE, there should be no jobs that depend on it. If there are, the call will fail. Oracle Database 11g: New Features for Administrators B - 26

File Watcher: Changes to Existing Attributes 11.2 File Watcher: Changes to Existing Attributes The EVENT_SPEC attribute for jobs and schedules can accept a file watcher name. File Watcher: Changes to Existing Attributes The EVENT_SPEC attribute for jobs and schedules can accept a file watcher name instead of a queue name. The resulting job/schedule will be event-based with the file watcher queue as its source queue. Oracle Database 11g: New Features for Administrators B - 27

File Watcher: New Dictionary Views 11.2 File Watcher: New Dictionary Views Query the following to view file watcher configuration information: DBA_SCHEDULER_FILE_WATCHERS ALL_SCHEDULER_FILE_WATCHERS USER_SCHEDULER_FILE_WATCHERS File Watcher: New Dictionary Views There are three new views with file watcher information: DBA_SCHEDULER_FILE_WATCHERS, ALL_SCHEDULER_FILE_WATCHERS, and USER_SCHEDULER_FILE_WATCHERS. The DBA_SCHEDULER_FILE_WATCHERS and ALL_SCHEDULER_FILE_WATCHERS views have the following columns (the USER_ view does not have an OWNER column): OWNER: Name of file watcher owner FILE_WATCHER_NAME: Name of the file watcher ENABLED: Should be either TRUE or FALSE depending on whether or not the file watcher is enabled DESTINATION: Remote destination where file will be located; set to NULL if the destination is the local machine. DIRECTORY_PATH: Path name of the directory where the file is located FILE_NAME: Name of the file to be found CREDENTIAL_OWNER: Name of the credential owner CREDENTIAL_NAME: Name of the credential MIN_FILE_SIZE: Minimum size of the file before file watcher will report that it has arrived STEADY_STATE_DURATION: Minimum amount of time the file has to stay unchanged before file watcher reports that it has arrived LAST_MODIFIED_TIME: Last time this file watcher was modified COMMENTS: Comments Oracle Database 11g: New Features for Administrators B - 28

File Watcher: New Columns in Existing Views 11.2 File Watcher: New Columns in Existing Views New columns in *_SCHEDULER_JOBS and the *_SCHEDULER_SCHEDULES views: Column Name Data type Description FILE_WATCHER_OWNER VARCHAR2(30) Name of file watcher owner. If not file watcher-based, this column will be NULL. FILE_WATCHER_NAME Name of file watcher. If not file watcher-based, this column will be NULL. File Watcher: New Columns in Existing Views New columns have been added to the *_SCHEDULER_JOBS and *_SCHEDULER_SCHEDULES views to provide file watcher information: FILE_WATCHER_NAME: Name of the file watcher FORCE: Force flag. When set to FALSE, the file watcher will not be dropped if there are any jobs that depend on it. Oracle Database 11g: New Features for Administrators B - 29

Scheduler Remote Database Jobs: Overview 11.2 Scheduler Remote Database Jobs: Overview Create a job that runs stored procedures and anonymous PL/SQL blocks on another database instance on the same host or on a remote host. The target database can be any release of Oracle Database. DBMS_SCHEDULER.CREATE_DATABASE_DESTINATION must be used to identify the remote database. DBMS_SCHEDULER.CREATE_CREDENTIAL must be used to identify the user. Jobs with job types of PLSQL_BLOCK and STORED_PROCEDURE can be the subject of SET_ATTRIBUTE calls for the DESTINATION and CREDENTIAL attributes. Scheduler Remote Database Jobs: Overview You can now create a job that runs stored procedures and anonymous PL/SQL blocks on another database instance on the same host or on a remote host. The target database can be any release of Oracle Database. There are no new procedures to support remote database jobs, rather there have been changes to existing DBMS_SCHEDULER procedures to support this functionality. DBMS_SCHEDULER.CREATE_DATABASE_DESTINATION must be used to identify the remote databases on which you want to run the remote database jobs. You must first register each remote database that you want to run a remote database job on by invoking DBMS_SCHEDULER.CREATE_DB_DESTINATION. DBMS_SCHEDULER.CREATE_CREDENTIAL must be used to identify the user that you want to connect as in the remote database. Additional information is provided on the following pages. Oracle Database 11g: New Features for Administrators B - 30

Using CREATE_DATABASE_DESTINATION 11.2 Using CREATE_DATABASE_DESTINATION Argument Data type Default DESTINATION_NAME VARCHAR2 No default AGENT TNS_NAME COMMENTS Null Using DBMS_SCHEDULER.CREATE_DATABASE_DESTINATION To create a remote database job, you must first create a database destination that represents the remote database by using the DBMS_SCHEDULER.CREATE_DATABASE_DESTINATION procedure. It has the following arguments: DESTINATION_NAME: Name of the destination representing the database that you want to connect to AGENT: Name of the external destination that represents the agent that is used to connect to the remote database TNS_NAME: Any valid Oracle Net connect identifier (net service name in the local database tnsnames.ora file or an actual Oracle Net connect string). If this argument is not specified, the scheduler agent must be configured such that it has a default database it connects to. COMMENTS: Comments Oracle Database 11g: New Features for Administrators B - 31

Using DROP_DATABASE_DESTINATION 11.2 Using DROP_DATABASE_DESTINATION Argument Data type Default DESTINATION_NAME VARCHAR2 No default All members of destination groups referring to this destination will be dropped. All the job instances that point to this destination will be dropped. Jobs running against this destination will be stopped. Using DBMS_SCHEDULER.DROP_DATABASE_DESTINATION Use the DBMS_SCHEDULER.DROP_DATABASE_DESTINATION procedure to drop a destination. It has the following argument: DESTINATION_NAME: Name of the destination representing the database that you want to connect to When a database destination is dropped, all members of the destination groups referring to this destination will also be dropped. When a database destination is dropped, all the job instances that point to this destination will be dropped. Jobs that are running against this destination will be stopped. Oracle Database 11g: New Features for Administrators B - 32

Creating Remote Database Jobs: Configuration 11.2 Creating Remote Database Jobs: Configuration Perform the following configuration steps: 1. Set up the originating database for remote jobs. 2. Name each remote database that you want to run remote database jobs on by using DBMS_SCHEDULER.CREATE_DB_DESTINATION. 3. Create credentials for all users that will connect on the remote databases by using DBMS_SCHEDULER.CREATE_CREDENTIAL. Creating Remote Database Jobs: Configuration You can perform the tasks listed in the slide to configure the environment for remote database jobs. Refer to Oracle Database Administrator's Guide 11g Release 2 for a detailed example. Oracle Database 11g: New Features for Administrators B - 33

Setting Up the Database for Remote Jobs 11.2 Setting Up the Database for Remote Jobs Verify that XML DB is installed. Enable HTTP connections to the database. Execute the prvtrsch.plb script. Set a registration password for the Scheduler agents: BEGIN DBMS_XDB.SETHTTPPORT(port); END; BEGIN DBMS_SCHEDULER.SET_AGENT_REGISTRATION_PASS('password'); END; Setting Up the Database for Remote Jobs Perform the steps listed in the slide on the originating database. Oracle Database 11g: New Features for Administrators B - 34

Creating Remote Database Jobs 11.2 Creating Remote Database Jobs Create the job by using DBMS_SCHEDULER.CREATE_JOB. Set the default credential by using the CREDENTIAL_NAME parameter. Set the destination by using the DESTINATION_NAME parameter. Enable the job by setting the ENABLED parameter to TRUE. Creating a Remote Database Job Use the DBMS_SCHEDULER.CREATE_JOB procedure to create each remote job. The CREATE_JOB procedure includes the following parameters that are applicable for remote database jobs: CREDENTIAL_NAME is used to specify the default credential to use with the job. The credential must exist. DESTINATION_NAME is used to specify the database destination or external destination for the job. Oracle Database 11g: New Features for Administrators B - 35

Scheduler Multiple Destination Jobs: Overview 11.2 Scheduler Multiple Destination Jobs: Overview This feature enables you to specify several targets on which your jobs should execute. It provides the ability to monitor and control the jobs from the database on which they were created. While running, a multiple destination job is viewed as a collection of jobs, which are near-identical copies of each other. All jobs will execute based on the time zone that is specified in the start date of the job or will use the time zone of the source database. Scheduler Multiple Destination Jobs: Overview The multiple destination jobs feature enables you to specify multiple targets on which the jobs should execute. You have the ability to monitor and control the jobs from the database at which you created them. The following capabilities are included: Specifying several databases or machines on which a job must execute Modifying a job scheduled on multiple targets as a single entity Stopping or dropping jobs running on one or more remote targets Finding out the status of job instances on all of a job’s targets Note that in the initial release of this feature, all destinations will run based on the time zone that is specified in the start date of the job or will default to the time zone of the source database. Oracle Database 11g: New Features for Administrators B - 36

Scheduler Multiple Destination Jobs: Terminology 11.2 Scheduler Multiple Destination Jobs: Terminology Term Definition Parent job Job created at the source Child job Copies that execute at the various destinations Job destination ID System-generated number that can be used to uniquely identify a job instance on a given destination Scheduler Multiple Destination Jobs: Terminology A job destination ID is a system-generated number that can be used to uniquely identify a job instance on a given destination. It is a number that uniquely identifies a (job name, target, credential) tuple. Oracle Database 11g: New Features for Administrators B - 37

Scheduler Multiple Destination Job States 11.2 Scheduler Multiple Destination Job States Parent Job State SUCCEEDED All child jobs for the last scheduled start time succeeded FAILED All child jobs failed SOME FAILED Some failed and some succeeded INCOMPLETE One or more child jobs are still working on the previous scheduled run when the parent is ready to start the next scheduled run. Scheduler Multiple Destination Jobs States The parent job state will be set as follows: SUCCEEDED if all child jobs for the last scheduled start time succeeded FAILED if all child jobs failed SOME FAILED if some failed and some succeeded INCOMPLETE if one or more child jobs are still working on the previous scheduled run when the parent is ready to start the next scheduled run Oracle Database 11g: New Features for Administrators B - 38

Creating Multiple Destination Jobs 11.2 Creating Multiple Destination Jobs To create a multiple destination job, perform the following steps: 1. Create a destination group that contains all the remote destinations by using the DBMS_SCHEDULER.CREATE_GROUP procedure. 2. Create the job by using DBMS_SCHEDULER.CREATE_JOB and set the destination to the name of a previously created destination group. 3. Add additional destinations by using DBMS_SCHEDULER.ADD_GROUP_MEMBER. Creating Multiple Destination Jobs You can create a multiple destination job as follows: 1. Create a destination group that contains all the remote destinations: CREATE_GROUP('group_name', 'group_type', 'member, member'); 2. Create the job and set the destination: CREATE_JOB(JOB_NAME=>'job_name', …, CREDENTIAL_NAME=>'credential_name', DESTINATION_NAME=> 'destination_name'); Note: JOB_TYPE must be set to PLSQL_BLOCK, STORED_PROCEDURE, or EXECUTABLE. 3. Add additional destinations: ADD_GROUP_MEMBER('group_name', 'member'); Oracle Database 11g: New Features for Administrators B - 39

Using Destination Groups for Multiple Destination Jobs 11.2 Using Destination Groups for Multiple Destination Jobs Destination group consists of a list of destinations. Destination group must be assigned to the DESTINATION_NAME attribute of the job. Multiple destination jobs of type EXECUTABLE require the DESTINATION_NAME attribute to be set to a destination group of group type EXTERNAL_DEST. Multiple destination jobs of type PLSQL_BLOCK or STORED_PROCEDURE require the DESTINATION_NAME attribute to be set to a destination group of type DB_DEST. Using Destination Groups for Multiple Destination Jobs A destination group, which consists of a list of destinations, can be referenced when creating a job. The job runs on all destinations in the group. When you want a job to run at multiple destinations, you must create a database destination group or external destination group and assign it to the DESTINATION_NAME attribute of the job. Multiple destination jobs of type EXECUTABLE must have their DESTINATION_NAME attribute set to a destination group of group type EXTERNAL_DEST. External destinations are automatically created when a scheduler agent is registered with the database. All registered external destinations are listed in the ALL_SCHEDULER_EXTERNAL_DESTS view. External destinations are removed when the agent is unregistered or by using DROP_AGENT_DESTINATION in situations where the host on which the agent runs is no longer accessible. Multiple destination jobs of type PLSQL_BLOCK or STORED_PROCEDURE must have their DESTINATION_NAME attribute set to a destination group of type DB_DEST. Database destinations are created by using the CREATE_DATABASE_DESTINATION procedure. All created database destinations are listed in the ALL_SCHEDULER_DB_DESTS view. They are removed by using DROP_DATABASE_DESTINATION. Oracle Database 11g: New Features for Administrators B - 40

Oracle Database 11g: New Features for Administrators B - 41 11.2 Using CREATE_GROUP Argument Data type Default GROUP_NAME VARCHAR2 No default GROUP_TYPE MEMBER NULL COMMENTS Using DBMS_SCHEDULER.CREATE_GROUP To create a remote database job, you must first create a destination group by using the DBMS_SCHEDULER.CREATE_GROUP procedure. It has the following arguments: GROUP_NAME: Name of the group GROUP_TYPE: Group type of WINDOW, EXTERNAL_DEST, or DB_DEST MEMBER: Optional list of names of group members with a format of [[schema.]credential@][schema.]destination COMMENTS: Comments Oracle Database 11g: New Features for Administrators B - 41

Using ADD_GROUP_MEMBER 11.2 Using ADD_GROUP_MEMBER Argument Data type Default GROUP_NAME VARCHAR2 No default MEMBER_NAME Using DBMS_SCHEDULER.ADD_GROUP_MEMBER To add a member to a group, use the DBMS_SCHEDULER.ADD_GROUP_MEMBER procedure. It has the following arguments: GROUP_NAME: Name of the group MEMBER_NAME: Name of one or more members to add to the group Members must match the type of the group. Oracle Database 11g: New Features for Administrators B - 42

Oracle Database 11g: New Features for Administrators B - 43 11.2 Using DROP_GROUP Argument Data type Default GROUP_NAME VARCHAR2 No default FORCE BOOLEAN Using DBMS_SCHEDULER.DROP_GROUP To drop a group, use the DBMS_SCHEDULER.DROP_GROUP procedure. It has the following arguments: GROUP_NAME: Name of the group FORCE: Future use When a group of DESTINATION type is dropped, the jobs that have their DESTINATION attribute set to this group will be disabled. All of the group’s job instances will be removed from the *_SCHEDULER_JOB_DESTS view when it is dropped. Oracle Database 11g: New Features for Administrators B - 43

Using REMOVE_GROUP_MEMBER 11.2 Using REMOVE_GROUP_MEMBER Argument Data type Default GROUP_NAME VARCHAR2 No default MEMBER_NAME Using DBMS_SCHEDULER.REMOVE_GROUP_MEMBER To remove a member from a group, use the DBMS_SCHEDULER.REMOVE_GROUP_MEMBER procedure. It has the following arguments: GROUP_NAME: Name of the group MEMBER_NAME: Name of one or more members to remove from the group If the member is a DESTINATION, any job instances that represent this destination will be removed from the ALL_SCHEDULER_JOB_DESTINATIONS view. Oracle Database 11g: New Features for Administrators B - 44

Modifications to Existing DBMS_SCHEDULER Procedures 11.2 Modifications to Existing DBMS_SCHEDULER Procedures CREATE_JOB, SET_ATTRIBUTE, and GET_ATTRIBUTE have two new arguments: CREDENTIAL_NAME: Fully qualified name of the credential DESTINATION_NAME: Fully qualified name of the destination or destination group STOP_JOB: Use to stop an individual child job running on a specific destination by providing the JOB_DEST_ID of that child job. ENABLE and DISABLE: Use to enable/disable external destinations, database destinations and groups. SOURCE_HOST and DESTINATION_HOST arguments of PUT_FILE and GET_FILE must specify valid external destination names. Modifications to Existing DBMS_SCHEDULER Procedures All versions of the CREATE_JOB procedures will have the following two additional arguments added to the end of the argument list: CREDENTIAL_NAME: Fully qualified name of the credential DESTINATION_NAME: Fully qualified name of the destination or destination group All jobs and chain steps will have two new attributes that can be set and retrieved respectively by using SET_ATTRIBUTE and GET_ATTRIBUTE: DESTINATION_NAME: Used to set the destinations for a particular job or chain step. Specify either a single named destination or the name of a group of type. CREDENTIAL_NAME: Used to set the credential of a single destination for this job or job step, or to set a default credential for all destinations when the destination attribute is the name of a destination group. When an external destination is disabled, all the database destinations that go through this agent will automatically be disabled as well. When a destination is disabled, all job instances that point to this destination will be disabled as well. STOP_JOB can be used to stop an individual child job running on a specific destination by providing JOB_DEST_ID of that child job instead of the job name. Oracle Database 11g: New Features for Administrators B - 45

Multiple Destination Jobs: New Dictionary Views 11.2 Multiple Destination Jobs: New Dictionary Views Query the following views for detailed information: *_SCHEDULER_DESTS: All destinations on which remote jobs can be scheduled *_SCHEDULER_EXTERNAL_DESTS: All agents that have registered with the database *_SCHEDULER_DB_DESTS: All databases on which users can scheduler remote database jobs *_SCHEDULER_GROUPS: Group information *_SCHEDULER_GROUP_MEMBERS: Member information *_SCHEDULER_JOB_DESTS: State of a job at a remote database Multiple Destination Jobs: New Dictionary Views The following new views display information about multiple destination jobs: *_SCHEDULER_DESTS: Shows all the destinations on which remote jobs can be scheduled. The views contain both the external destinations (for remote external jobs) as well as the database destinations for remote database jobs. *_SCHEDULER_EXTERNAL_DESTS: Shows all the agents that have registered with the database and can be used as a destination for remote external jobs *_SCHEDULER_DB_DESTS: Shows all the databases on which you can schedule remote database jobs *_SCHEDULER_GROUPS: Shows the groups in your schema or all groups in the database *_SCHEDULER_GROUP_MEMBERS: Shows the group members in your schema or all group members in the database *_SCHEDULER_JOB_DESTS: Shows the state of a job at a remote database Oracle Database 11g: New Features for Administrators B - 46

Multiple Destination Jobs: New Columns in Existing Dictionary Views 11.2 Multiple Destination Jobs: New Columns in Existing Dictionary Views The following views have new columns providing additional information for multiple destination jobs: *_SCHEDULER_JOBS *_SCHEDULER_RUNNING_JOBS *_SCHEDULER_JOB_RUN_DETAILS *_SCHEDULER_JOB_LOG Multiple Destination Jobs: New Columns in Existing Dictionary Views The following dictionary views contain new columns with information about multiple destination jobs: *_SCHEDULER_JOBS: CREDENTIAL_OWNER: Name of the credential owner CREDENTIAL_NAME: Name of the source database DESTINATION_OWNER: Name of the destination owner NUMBER_OF_DESTINATIONS: Number of destinations associated with this job *_SCHEDULER_RUNNING_JOBS, *_SCHEDULER_JOB_RUN_DETAILS and *_SCHEDULER_JOB_LOG: CREDENTIAL_NAME: Name of the credential DESTINATION: Name of the destination Oracle Database 11g: New Features for Administrators B - 47

Oracle Database 11g: New Features for Administrators B - 48 Summary In this lesson, you should have learned how to: Use lightweight jobs Use Scheduler email notification Create a file watcher Create remote database jobs Create multiple destination jobs Oracle Database 11g: New Features for Administrators B - 48