Oracle SQL Plus The Definitive Guide- P31 pot

< previous page page_270 next page > Page 270 to doing this. First, set up some COLUMN commands with NEW_VALUE clauses. You need one of these COLUMN commands for each distinct value in your input string. In keeping with the owner.table example, the following two commands could be used: COLUMN owner_name NOPRINT NEW_VALUE s_owner_name COLUMN table_name NOPRINT NEW_VALUE s_table_name Next, you need to execute a query that returns the results you want. In this case, the query needs to return the owner name and table name as separate columns. Be sure to use column aliases to name these columns, and be sure those aliases match the names used in the COLUMN commands. The following SELECT takes a string in the form owner. table, and returns two separate values. If the owner is not specified, the name of the current user is returned instead. SELECT DECODE(INSTR(&&1,.), 0,USER, /*Default to current user.*/ UPPER(SUBSTR(&&1,1,INSTR(&&1,.)-1))) owner_name, DECODE(INSTR(&&1,.), 0,UPPER(&&1), /*Only the table name was passed in.*/ UPPER(SUBSTR(&&1,INSTR(&&1,.)+1))) table_name FROM dual; Once the query has been executed, the substitution variables named in the COLUMN commands will hold the values returned by the SELECT. These substitution variables may now be used in the remainder of the script. The following is a rewrite of the previous SELECT using these variables: SELECT SUM(bytes) FROM dba_extents WHERE segment_name &&s_table_name AND owner = &&s_owner_name; By using this technique, you have one point of change that controls how the input is parsed. If there's a bug in your logic, you only need to fix it in one place. The readability of your script is greatly increased, too. Your scripts will also be more clearly understood by others, and probably by yourself as well. Error Handling SQL*Plus doesn't offer too much in the way of error handling. By default, SQL*Plus simply ignores errors and goes on to execute either the next command you type in, or the next command in the script you are running. For interactive use, this is good enough. If an error occurs, you will see the message and take appropriate action. However, the situation is different when you are running a script. Depending on what the script is doing, you may not want SQL*Plus to blindly proceed to the next command when an error occurs. Consider the following script, which creates a new table, copies data to it, then deletes the original table: < previous page page_270 next page > < previous page page_271 next page > Page 271 CREATE TABLE employees AS SELECT * FROM employee; DROP TABLE employee; If the CREATE TABLE command failed, you certainly wouldn't want the script to continue, because you would lose all your data! To help with this type of situation, SQL*Plus provides the WHENEVER command. The Whenever Command With the WHENEVER command, you can give SQL*Plus instructions on what to do when an error occurs. Your choices are a bit limited: you can either continue when an error occurs, or you can exit SQL*Plus entirely, possibly returning an error code. Returning an error code is useful if you are calling SQL*Plus from a Unix shell script or a DOS batch file. There are two types of errors you can handle with WHENEVER. Each has its own variation of the command. WHENEVER SQLERROR is used to handle SQL errors and errors raised from PL/SQL blocks. WHENEVER OSERROR is used to handle operating system errors, such as those you might get when you run out of disk space while spooling a large data extract. There is one type of error you cannot detect: an error involving a SQL*Plus command. An example would be if you were to misspell a command, such as COLUMN. If your script contained a command like the following: COLUM employee_name HEADEEN Employee Name FLOORMAT A40 SQL*PLus would generate an error and continue on with the script as if nothing had happened. This isn't as much of a problem as you might first think. You should test your scripts to be sure your SQL*Plus commands are correct. This is easy to do, and the consequences of a failed SQL*Plus command are usually no worse than some messy formatting of the output. SQL commands, on the other hand, can fail for a variety of reasons that don't involve simple misspellings. A simple database change can easily cause a SQL command that worked one day to fail the next. Similarly, with operating- system errors, you don't know in advance when you will run out of disk space. WHENEVER SQLERROR The WHENEVER SQLERROR command tells SQL*Plus what to do when a SQL statement or PL/SQL block fails to execute properly. The simplest way to use it is to issue the following command, which tells SQL*Plus to simply abort the script when an error occurs. WHENEVER SQLERROR EXIT < previous page page_271 next page > < previous page page_272 next page > Page 272 Now, when a SQL error occurs, SQL*Plus will exit, as the following example shows: SQL> WHENEVER SQLERROR EXIT SQL> SELECT kristi FROM dual; SELECT kristi FROM dual * ERROR at line 1: ORA-00904: invalid column name Disconnected from Oracle7 Server Release 7.3.3.0.0 - Production Release PL/SQL Release 2.3.3.0.0 - Production $ When SQL*Plus exits like this, the default behavior is to commit any transaction that might be open. For a simple SELECT statement like that shown in the previous example, this is not a problem. When you are changing records, it might be. If your script executes several SQL statements that change data, you may not want to commit unless all the changes can be made. In this situation, use the ROLLBACK option to tell SQL*Plus to roll back when an error occurs, like this: WHENEVER SQLERROR EXIT ROLLBACK If you're calling SQL*Plus from a Unix shell script, DOS batch file, VMS command file, or the equivalent, you can have it pass back a return code so your shell script can tell whether your script executed successfully or not. The following command tells SQL*Plus to pass back a standard failure code when an error occurs: WHENEVER SQLERROR EXIT FAILURE ROLLBACK The precise code that gets passed back will vary from one operating system to the next. If a simple success/fail indication is not enough, you can have SQL*Plus pass back the specific Oracle error code or any other value you want. The following example shows how to pass back the Oracle error code when a SQL error occurs: WHENEVER SQLERROR EXIT SQL.SQLCODE You could also choose to return any arbitrary number, the value of a numeric bind variable, or the value of a substitution variable. The default behavior of WHENEVER SQLERROR EXIT is to COMMIT any pending transaction. You may want to use the ROLLBACK option to change that behavior. Using WHENEVER SQLERROR EXIT with the GUI version of SQL*Plus can be really annoying at times. Any error results in SQL*Plus terminating, causing the GUI window to close. Usually this happens before you even realize that an error occurred, making you miss any error message that may have been displayed. Don't use THEN. It's WHENEVER SQLERROR EXIT, not WHENEVER SQLERROR THEN EXIT. I tend to get mixed up on this point often. < previous page page_272 next page > < previous page page_273 next page > Page 273 PL/SQL errors and WHENEVER The WHENEVER SQLERROR EXIT command will catch any errors in a PL/SQL block, but only if those errors are raised back to the SQL*Plus level. PL/SQL has its own error-handling mechanism, and using it can prevent SQL*Plus from knowing that an error ever occurred. The following PL/SQL block does not contain an error handler, so any SQL errors will be implicitly raised to the calling routine, which in this case is SQL*Plus: BEGIN UPDATE employee SET employee_billing_rate = employee_billing_rate * 1.10; COMMIT; END; / However, you could rewrite the block so that it includes an error handler. In that case, the PL/SQL error handler would get the error, and SQL*Plus would not know about it. Here is the same block, but with an error handler: DECLARE success_flag BOOLEAN; BEGIN BEGIN UPDATE employee SET employee_billing_rate = employee_billing_rate * 1.10; success_flag := TRUE; EXCEPTION WHEN OTHERS THEN success_flag := false; END; IF success_flag THEN COMMIT; ELSE ROLLBACK; DBMS_OUTPUT.PUT_LINE(The UPDATE failed.); END IF; END; / In this example, the UPDATE statement is contained in its own PL/SQL block, and any error related to that statement will be trapped by the exception handler for that block. Even if an error occurs, as far as SQL*Plus is concerned, this block will have executed successfully. If you want to handle an error within PL/SQL, but still abort the SQL*Plus script, you can use the RAISE_APPLICATION_ERROR procedure. This procedure is part of a PL/SQL package named DBMS_STANDARD, and should exist in all installations. You call it like this: RAISE_APPLICATION_ERROR (error_code, error_message); < previous page page_273 next page > < previous page page_274 next page > Page 274 where: error_code Is a negative number. The range from -20000 to -20999 is reserved for userdefined errors. error_message Is a text message of up to 2048 characters. When you call RAISE_APPLICATION_ERROR from a PL/SQL block, control immediately returns to the calling block. You must call the procedure from the outermost PL/SQL block in order to return the error to SQL*Plus. When that happens, SQL*Plus will print the error message and then take whatever action you specified in the most recent WHENEVER SQLERROR command. The next PL/SQL block is the same as the previous one, except for the addition of the RAISE_APPLICATION_ERROR command, which is used to notify SQL*Plus of an error: DECLARE success_flag BOOLEAN; BEGIN BEGIN UPDATE employee SET employee_billing_rate = employee_billing_rate * 1.10; success_flag := TRUE; EXCEPTION WHEN OTHERS THEN success_flag := false; END; IF success_flag THEN COMMIT; ELSE ROLLBACK; DBMS_OUTPUT.PUT_LINE(The UPDATE failed.); RAISE_APPLICATION_ERROR (-20000, The UPDATE of employee billing rates failed.); END IF; END; / Now if an error occurs, SQL*Plus will know about it and can abort the script. WHENEVER OSERROR The WHENEVER OSERROR command tells SQL*Plus what to do when an operating system error occurs. Running out of disk space would be a likely operating-system error, one that you might encounter when spooling large amounts of output from a SQL query. < previous page page_274 next page > < previous page page_275 next page > Page 275 WHENEVER OSERROR works pretty much the same as the WHENEVER SQLERROR command. The simple version, which just causes SQL*Plus to exit when an error occurs, looks like this: WHENEVER OSERROR EXIT By default, any changes are committed when SQL*Plus exits. You can change that behavior using the ROLLBACK keyword as follows: WHENEVER OSERROR EXIT ROLLBACK As with WHENEVER SQLERROR, you can pass a return code back to a shell script in order to allow it to detect the error. For example: WHENEVER OSERROR EXIT FAILURE Unlike the SQLERROR version of the command, there is no equivalent to SQL.SQL-CODE for operating-system errors. The other options still apply, however, and you can return an arbitrary value, the value from a bind variable, or the value of a substitution variable. Be aware that the range of return codes you can pass back from SQL*Plus varies from one operating system to the next. Under Unix, return codes are limited to one byte, giving you a range of 0 to 255 to work with. VMS, on the other hand, allows much larger values to be returned. Keep this in mind if you are writing a script that needs to be portable across different operating systems. The following example archives any project_hours data over one year old to a file, then deletes the data that was archived. In order to be sure no data is deleted without first being successfully archived, the WHENEVER commands are used to abort the script in the event of an error. WHENEVER SQLERROR EXIT FAILURE WHENEVER OSERROR EXIT FAILURE Turn off page headings, column titles, etc. SET PAGESIZE 0 SET HEADING OFF SET COLSEP , Archive old records SPOOL project_hours_archive.txt SELECT * FROM project_hours WHERE TRUNC(time_log_date) <= ADD_MONTHS(TRUNC(SySDATE),-12); SPOOL OFF < previous page page_275 next page > < previous page page_276 next page > Page 276 Delete the records just archived DELETE FROM project_hours WHERE TRUNC(time_log_date) <= ADD_MONTHS (TRUNC (SYSDATE),-12); < previous page page_276 next page > < previous page page_277 next page > Page 277 8 Tuning and Timing In this chapter: Using SQL*Plus Timers Using EXPLAIN PLAN Using AUTOTRACE Improving on EXPLAIN PLAN Results Where to Find more Tuning Information Oracle offers two features that can be used from SQL*Plus to monitor and improve the performance of your scripts and SQL statements. These two features are SQL*Plus timers and the EXPLAIN PLAN command. SQL*Plus has a timing feature built into it that can be used to monitor the length of time it takes to execute a SQL command, a PL/SQL block, or any other part of a script. To measure the time it takes to execute a SQL statement, you start a timer prior to executing the statement, then display the value of the timer immediately after the statement is executed. The EXPLAIN PLAN command, although it is a SQL command, not a SQL*Plus command, is often used from SQL*Plus. EXPLAIN PLAN can be used to find out exactly how Oracle intends to execute any given SQL query. It will tell you, for example, whether or not an index will be used, and what the name of that index will be. Once you know how Oracle intends to execute the query, you can use hints to influence or alter Oracle's default plan based on your knowledge of the data. A hint is a command to the optimizer that is embedded in a comment within a SQL query. The optimizer is the part of Oracle that determines how best to retrieve the data required by a SQL statement. This chapter is not intended to be an exhaustive reference for tuning SQL statements. Several good books have been written on this subject. What this chapter does provide is a quick overview of the mechanics of tuning and a convenient summary of the hints available to you. Using SQL*Plus Timers SQL*Plus has a crude timing facility built into it that allows you to measure the elapsed time of a script or any portion of a script. You can even have SQL*Plus < previous page page_277 next page > < previous page page_278 next page > Page 278 report the elapsed execution time of every SQL query and PL/SQL block automatically after each statement has executed. Timers can be nested so that you can time the overall execution of a script as well as the execution time of each individual statement. Timer resolution varies with the hardware platform being used. Under Windows NT or 95, the elapsed time is reported in milliseconds. Under HP Unix, it is resolved only to the hundredth of a second, but the display format is much nicer. Here is how an elapsed time of 90.5 seconds will be shown under Windows: real: 90500 90,500 milliseconds is equivalent to 90.5 seconds. With Unix versions of SQL*Plus, the display is much more user- friendly. Here's how the HP-UX version of SQL*Plus would report the same value: Elapsed: 00:01:30.5 Unix uses an hour, minute, second, and hundredths format, so 90.5 seconds is reported as 1 minute, 30 seconds, and 50 hundredths. Remember, the timer is a SQL*Plus timer. The hardware that matters is the machine running the SQL*Plus executable, not the one running the Oracle server. Timings can be useful in spotting trends. It may be helpful to know, for example, if a script is taking longer and longer to run. Timings can also be helpful in comparing the relative efficiency of two SQL statements. If you have two statements that return equivalent results, and one consistently runs faster than the other, that's the one you probably want to go with. Take timing with a grain of salt, though. The timer measures elapsed time, not CPU time, and many factors can throw it off. The network throughput may vary between the execution of two queries. The load on the server could vary as well. For example, one query might run more slowly than another simply because many other users all happened to hit the database at the same time. Be skeptical of once-off results. Look for consistency over several timings. The SET TIMING Command You can have SQL*Plus automatically report the elapsed time it takes to execute every query by using the SET TIMING ON command. For example: SQL> SET TIMING ON Now, whenever you execute a query, SQL*Plus will report the elapsed time. With the Windows versions of SQL*Plus, this time will be reported in milliseconds. The following example shows that it took 110 milliseconds, or about 1/10 of a second, for a query on DBA_VIEWS to complete: < previous page page_278 next page > . Remember, the timer is a SQL* Plus timer. The hardware that matters is the machine running the SQL* Plus executable, not the one running the Oracle server. Timings can be useful in spotting trends to the calling block. You must call the procedure from the outermost PL /SQL block in order to return the error to SQL* Plus. When that happens, SQL* Plus will print the error message and then. your SQL* Plus commands are correct. This is easy to do, and the consequences of a failed SQL* Plus command are usually no worse than some messy formatting of the output. SQL commands, on the other