07 Using Oracle-Supported Package in Application Development

Editor's Notes

• #3: Using UTL_MAIL The UTL_MAIL package is a utility for managing e-mail that includes commonly used e-mail features such as attachments, CC, BCC, and return receipt. The UTL_MAIL package is not installed by default because of the SMTP_OUT_SERVER configuration requirement and the security exposure this involves. When installing UTL_MAIL , you should take steps to prevent the port defined by SMTP_OUT_SERVER being swamped by data transmissions. To install UTL_MAIL , log in as a DBA user in i SQL*Plus and execute the following scripts: @$ORACLE_HOME/rdbms/admin/utlmail.sql @$ORACLE_HOME/rdbms/admin/prvtmail.plb You should define the SMTP_OUT_SERVER parameter in the init.ora file database initialization file: SMTP_OUT_SERVER=mystmpserver.mydomain.com The SMTP_OUT_SERVER parameter specifies the SMTP host and port to which UTL_MAIL delivers out bound e-mail. Multiple servers can be specified, separated by commas. If the first server in the list is unavailable, then UTL_MAIL tries the second server, and so on. If SMTP_OUT_SERVER is not defined, then this invokes a default setting derived from DB_DOMAIN , which is a database initialization parameter specifying the logical location of the database within the network structure. For example: db_domain=mydomain.com
• #4: Installing and Using UTL_MAIL The slide shows how to configure the SMTP_OUT_SERVER parameter to the name of the SMTP host in your network, and how to install the UTL_MAIL package that is not installed by default. Changing the SMTP_OUT_SERVER parameter requires restarting the database instance. These tasks are performed by a user with SYSDBA capabilities. The last example in the slide shows the simplest way to send a text message by using the UTL_MAIL.SEND procedure with at least a subject and a message. The first two required parameters are the following : The sender e-mail address (in this case, [email_address] ) The recipients e-mail address (for example, [email_address] ). The value can be a comma-separated list of addresses. The UTL_MAIL.SEND procedure provides several other parameters, such as cc , bcc , and priority with default values, if not specified. In the example, the message parameter specifies the text for the e-mail, and the subject parameter contains the text for the subject line. To send an HTML message with HTML tags, add the mime_type parameter (for example, mime_type=>'text/html' ). Note: For details about all the UTL_MAIL procedure parameters, refer to the PL/SQL Packages and Types Reference 10g manual.
• #5: DBMS_SCHEDULER Package Oracle Database 10 g provides a collection of subprograms in the DBMS_SCHEDULER package to simplify management and to provide a rich set of functionality for complex scheduling tasks. Collectively, these subprograms are called the Scheduler and can be called from any PL/SQL program. The Scheduler enables database administrators and application developers to control when and where various tasks take place. By ensuring that many routine database tasks occur without manual intervention, you can lower operating costs, implement more reliable routines, and minimize human error. The diagram shows the following architectural components of the Scheduler: A job is the combination of a program and a schedule. Arguments required by the program can be provided with the program or the job. All job names are of the form [schema.]name . When you create a job, you specify the job name, a program, a schedule, and (optionally) job characteristics that can be provided through a job class . A program determines what should be run. Every automated job involves a particular executable, whether it is a PL/SQL block, a stored procedure, a native binary executable, or a shell script. A program provides metadata about a particular executable and may require a list of arguments. A schedule specifies when and how many times a job is executed.
• #6: Creating a Job The component that causes something to be executed at a specified time is called a job . Use the DBMS_SCHEDULER.CREATE_JOB procedure of the DBMS_SCHEDULER package to create a job, which is in a disabled state by default. A job becomes active and scheduled when it is explicitly enabled. To create a job, you: Provide a name in the form [schema.]name Need the CREATE JOB privilege Note: A user with the CREATE ANY JOB privilege can create a job in any schema except the SYS schema. Associating a job with a particular class requires the EXECUTE privilege for that class. In simple terms, a job can be created by specifying all the job details — the program to be executed (what) and its schedule (when) — in the arguments of the CREATE_JOB procedure. Alternatively, you can use predefined Program and Schedule components. If you have a named Program and Schedule, then these can be specified or combined with in-line arguments for maximum flexibility in the way a job is created. A simple logical check is performed on the schedule information (that is, checking the date parameters when a job is created). The database checks whether the end date is after the start date. If the start date refers to a time in the past, then the start date is changed to the current date.
• #7: Managing Jobs After a job has been created, you can: Run the job by calling the RUN_JOB procedure specifying the name of the job. The job is immediately executed in your current session. Stop the job by using the STOP_JOB procedure. If the job is running currently, it is stopped immediately. The STOP_JOB procedure has two arguments: job_name : Name of the job to be stopped force : Tries to gracefully terminate a job. If this fails and force is set to TRUE , then the job slave is terminated. (Default value is FALSE ). To use force , you must have the MANAGE SCHEDULER system privilege. Drop the job with the DROP_JOB procedure. This procedure has two arguments: job_name : Name of the job to be dropped force : Whether the job should be stopped and dropped if it is currently running (Default value is FALSE .) If the DROP_JOB procedure is called and the job specified is currently running, then the command fails unless the force option is set to TRUE . If the force option is set to TRUE , then any instance of the job that is running is stopped and the job is dropped. Note: To run, stop, or drop a job that belongs to another user, you need ALTER privileges on that job or the CREATE ANY JOB system privilege.
• #8: Data Dictionary Views The DBA_SCHEDULER_JOB_LOG view shows all completed job instances, both successful and failed. To view the state of your jobs, use the following query: SELECT job_name, program_name, job_type, state FROM USER_SCHEDULER_JOBS; To determine which instance a job is running on, use the following query: SELECT owner, job_name, running_instance, resource_consumer_group FROM DBA_SCHEDULER_RUNNING_JOBS; To determine information on how a job ran, use the following query: SELECT job_name, instance_id, req_start_date, actual_start_date, end_date, completion_status FROM ALL_SCHEDULER_JOB_LOG; To determine the status of your jobs, use the following query: SELECT job_name, status, error#, run_duration, cpu_used FROM USER_SCHEDULER_JOB_RUN_DETAILS;
• #10: Steps to Process SQL Statements All SQL statements have to go through various stages. However, some stages may not be relevant for all statements. The following are the key stages: Parse: Every SQL statement must be parsed. Parsing the statement includes checking the statement's syntax and validating the statement, ensuring that all references to objects are correct and that the relevant privileges to those objects exist. Bind: After parsing, the Oracle server may need values from or for any bind variable in the statement. The process of obtaining these values is called binding variables. This stage may be skipped if the statement does not contain bind variables. Execute: At this point, the Oracle server has all necessary information and resources, and the statement is executed. For nonquery statements, this is the last phase. Fetch: In the fetch stage, which is applicable to queries, the rows are selected and ordered (if requested by the query), and each successive fetch retrieves another row of the result, until the last row has been fetched.
• #11: Dynamic SQL The embedded SQL statements available in PL/SQL are limited to SELECT , INSERT , UPDATE , DELETE , COMMIT , and ROLLBACK , all of which are parsed at compile time; that is, they have a fixed structure. You need to use dynamic SQL functionality if you require: The structure of a SQL statement to be altered at run time Access to DDL statements and other SQL functionality in PL/SQL To perform these kinds of tasks in PL/SQL, you must construct SQL statements dynamically in character strings and execute them using either of the following: Native Dynamic SQL statements with EXECUTE IMMEDIATE DBMS_SQL package The process of using SQL statements that are not embedded in your source program and are constructed in strings and executed at run time is known as “dynamic SQL.” Tthe SQL statements are created dynamically at run time and can access and use PL/SQL variables. For example, you create a procedure that uses dynamic SQL to operate on a table whose name is not known until run time, or execute a data definition language (DDL) statement (such as CREATE TABLE ), a data control statement (such as GRANT ), or a session control statement (such as ALTER SESSION ).
• #12: Native Dynamic SQL In Oracle 8 and earlier releases, the only way to implement dynamic SQL in a PL/SQL application was by using the DBMS_SQL package. With Oracle 8 i and later releases, the PL/SQL environment provides Native Dynamic SQL as an alternative. Native Dynamic SQL provides the ability to dynamically execute SQL statements whose structure is constructed at execution time. The following statements have been added or extended in PL/SQL to support Native Dynamic SQL: EXECUTE IMMEDIATE : Prepares a statement, executes it, returns variables, and then deallocates resources OPEN-FOR : Prepares and executes a statement using a cursor variable FETCH : Retrieves the results of an opened statement by using the cursor variable CLOSE : Closes the cursor used by the cursor variable and deallocates resources You can use bind variables in the dynamic parameters in the EXECUTE IMMEDIATE and OPEN statements. Native Dynamic SQL includes the following capabilities: Define a dynamic SQL statement Bind instances of any SQL data types supported in PL/SQL Handle IN , IN OUT , and OUT bind variables that are bound by position, not by name
• #13: Dynamically Executing a PL/SQL Block The annual_sal function dynamically constructs an anonymous PL/SQL block. The PL/SQL block contains bind variables for: The input of the employee ID using the :empid placeholder The output result computing the annual employees salary using the placeholder called :res Note: This example demonstrates how to use the OUT result syntax (in the USING clause of the EXECUTE IMMEDIATE statement) to obtain the result calculated by the PL/SQL block. The procedure output variables and function return values can be obtained in a similar way from a dynamically executed anonymous PL/SQL block.
• #14: Using Native Dynamic SQL to Compile PL/SQL Code The compile_plsql procedure in the example can be used to compile different PL/SQL code using the ALTER DDL statement. Four basic forms of the ALTER statement are shown to compile: A procedure A function A package specification A package body Note: If you leave out the keyword SPECIFICATION or BODY with the ALTER PACKAGE statement, then the specification and body are both compiled. Here are examples of calling the procedure in the slide for each of the four cases, respectively: EXEC compile_plsql ('list_employees', 'procedure') EXEC compile_plsql ('get_emp', 'function') EXEC compile_plsql ('mypack', 'package', 'specification') EXEC compile_plsql ('mypack', 'package', 'body') Compiling with DEBUG enabled for the get_emp function: EXEC compile_plsql ('get_emp', 'function', 'debug')
• #15: Using the DBMS_SQL Package Using DBMS_SQL , you can write stored procedures and anonymous PL/SQL blocks that use dynamic SQL, such as executing DDL statements in PL/SQL—for example, executing a DROP TABLE statement. The operations provided by this package are performed under the current user, not under the package owner SYS . The DBMS_SQL package provides the following subprograms to execute dynamic SQL: OPEN_CURSOR to open a new cursor and return a cursor ID number PARSE to parse the SQL statement, that is, it checks the statement syntax and associates it with the opened cursor. DDL statements are immediately executed when parsed. BIND_VARIABLE to bind a given value to a bind variable identified by its name in the statement being parsed. Not needed if the statement does not have bind variables. EXECUTE to execute the SQL statement and return the number of rows processed FETCH_ROWS to retrieve the next row for a query (use in a loop for multiple rows) CLOSE_CURSOR to close the specified cursor Note: Using the DBMS_SQL package to execute DDL statements can result in a deadlock. For example, the most likely reason is that the package is being used to drop a procedure that you are still using.
• #16: Comparison of Native Dynamic SQL and the DBMS_SQL Package Native Dynamic SQL provides the following advantages over the DBMS_SQL package. Ease of use: Because Native Dynamic SQL is integrated with SQL, you can use it in the same way that you currently use static SQL within PL/SQL code. The code is typically more compact and readable compared with the code written with the DBMS_SQL package. Performance improvement: Native Dynamic SQL performs significantly better than DBMS_SQL , in most circumstances, due to native support provided by the PL/SQL interpreter. The DBMS_SQL approach uses a procedural API and suffers from high procedure call and data copy overhead. Support for user-defined types: Native Dynamic SQL supports all the types supported by static SQL in PL/SQL. Therefore, Native Dynamic SQL provides support for user-defined types such as user-defined objects, collections, and REFs. The DBMS_SQL package does not support these user-defined types. However, it has limited support for arrays. Support for fetching into records: With Native Dynamic SQL, the rows resulting from a query can be directly fetched into PL/SQL records. The DBMS_SQL package does not support fetching into records structures.
• #17: Practice 5: Overview In this practice, you use UTL_FILE to generate a text file report of employees in each department. You create a procedure to generate an HTML version of the employee report, and write a SQL script file to spool the results to a text file. You use the DBMS_SCHEDULER to run the first report that creates a text file every 5 minutes.