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 foll
Trang 1< 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:
Trang 2
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
Trang 3
< 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
Trang 5
< 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);
Trang 6
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
Trang 7
< 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
Trang 8
Delete the records just archived
DELETE
FROM project_hours
WHERE TRUNC(time_log_date) <= ADD_MONTHS (TRUNC (SYSDATE),-12);
Trang 9
< 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
Trang 10
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: