Error Management Features of PLSQL - dryfta-assets.s3 ... · Copyright © 2018Oracle and/or its...

Copyright©2014Oracleand/oritsaffiliates.Allrightsreserved.|

PL/SQL – The KISS programming language

Error Management Featuresof Oracle PL/SQL

1

Copyright©2018 Oracleand/oritsaffiliates.Allrightsreserved.| 2

ResourcesforOracleDatabaseDevelopers• OfficialhomeofPL/SQL- oracle.com/plsql• SQL-PL/SQLdiscussionforumonOTNhttps://community.oracle.com/community/database/developer-tools/sql_and_pl_sql

• PL/SQLandEBRblogbyBrynLlewellyn- https://blogs.oracle.com/plsql-and-ebr

• OracleLearningLibrary- oracle.com/oll• WeeklyPL/SQLandSQLquizzes,andmore- devgym.oracle.com• AskTom- asktom.oracle.com – 'nuff said• LiveSQL- livesql.oracle.com – scriptrepositoryand12/712cdatabase• oracle-developer.net - greatcontentfromAdrianBillington• oracle-base.com - greatcontentfromTimHall


ErrorManagementinPL/SQL• Definingexceptions• Raisingexceptions• Handlingexceptions

• Let’sstartwithquizzestotestyourknowledgeofthebasicmechanicsofexceptionhandlinginPL/SQL.

Allreferencedcodeisavailableatlivesql.oracle.com andinmydemo.zip filefromthe

PL/SQLLearningLibrary:oracle.com/oll/plsql.


Quiz:Whenstringsdon'tfit...(1)

DECLAREaname VARCHAR2(5);

BEGINBEGIN

aname := 'Big String';DBMS_OUTPUT.PUT_LINE (aname);

EXCEPTIONWHEN VALUE_ERROR THEN

DBMS_OUTPUT.PUT_LINE ('Inner block');END;DBMS_OUTPUT.PUT_LINE ('What error?');

EXCEPTIONWHEN VALUE_ERROR THEN

DBMS_OUTPUT.PUT_LINE ('Outer block');END;

excquiz1.sqllivesql.oracle.com "TestYourPL/SQLExceptionHandlingKnowledge"

• Whatdoyouseeafterrunningthisblock?


Quiz:Whenstringsdon'tfit...(2)

DECLAREaname VARCHAR2(5);

BEGINDECLARE

aname VARCHAR2(5) := 'Big String';BEGIN

DBMS_OUTPUT.PUT_LINE (aname);

EXCEPTIONWHEN VALUE_ERRORTHEN

DBMS_OUTPUT.PUT_LINE ('Inner block');END;DBMS_OUTPUT.PUT_LINE ('What error?');

EXCEPTIONWHEN VALUE_ERRORTHEN

DBMS_OUTPUT.PUT_LINE ('Outer block');END;/

excquiz2.sql

• Whatdoyouseeafterrunningthisblock?


DefiningExceptions• TheEXCEPTIONisalimitedtypeofdata.

– Hasjusttwoattributes:codeandmessage.– YoucanRAISEandhandleanexception,butitcannotbepassedasanargumentinaprogram.

• AssociatenameswitherrornumberswiththeEXCEPTION_INITpragma.


TheEXCEPTION_INITPragma

• UseEXCEPTION_INITto...– GivenamestoOracleerrorcodesforwhichnoexceptionwasdefined.– Assignanerrorcodeotherthan1toauser-definedexception(usuallyinthe-20NNNrangeusedbyRAISE_APPLICATION_ERROR).

CREATE OR REPLACE PROCEDURE upd_for_dept (dept_in IN employee.department_id%TYPE

, newsal_in IN employee.salary%TYPE)IS

e_forall_failure EXCEPTION;PRAGMA EXCEPTION_INIT (e_forall_failure, -24381);

exception_init.sqllivesql.oracle.com search"exception_init"


RaisingExceptions• RAISEraisesthespecifiedexceptionbyname.

– RAISE;re-raisescurrentexception.Callableonlywithintheexceptionsection.

• RAISE_APPLICATION_ERROR– Communicatesanapplicationspecificerrorbacktoanon-PL/SQLhostenvironment.– Errornumbersrestrictedtothe-20,999- -20,000range.


TheRAISEStatement• UseRAISEtoraiseaspecific,namedexceptionortore-raise thecurrentexception.– Raisepre-definedanduser-definedexceptions.

• "RAISE;"re-raisesthecurrentexception.– YoucanonlyuseRAISE;fromwithinanexceptionhandler.

e_forall_failure EXCEPTION;PRAGMA EXCEPTION_INIT (e_forall_failure, -24381);

BEGIN...RAISE e_forall_failure;

EXCEPTIONWHEN e_forall_failiure THEN

log_error();RAISE;

WHEN OTHERS THENlog_error();RAISE;

raise.sqlreraise.sql


CommunicatingApplicationErrors• WhenOracleraisesanexception,itprovidestheerrorcodeanderrormessage.

• Whenanapplication-specificerroroccurs,suchas"Accountbalancetoolow",itisuptoyou,thedeveloper,tocommunicateallnecessaryinformationtotheuser.– Thiscaninvolveanerrorcode,errormessage,orboth.

• Forthis,youmustuseRAISE_APPLICATION_ERROR.– And,really,thatistheonlytime.


Definingapplication-specificmessages• Youcanraiseanapplication-specificerrorwithRAISE,butyoucannotpassbackanapplication-specificmessage thatway.

• WithRAISE_APPLICATION_ERROR,youcanissueyourown"ORA-"errormessages.– Thisbuilt-inreplacesthevaluesthatwouldnormallybereturnedwithacalltoSQLCODEandSQLERRMwithyour values.

• Thisinformationcanbedisplayedtotheuserorsenttotheerrorlog.


RAISE_APPLICATION_ERRORExampleIF :NEW.birthdate > ADD_MONTHS (SYSDATE, -1 * 18 * 12)THEN

RAISE_APPLICATION_ERROR (-20070, ‘Employee must be 18.’);

END IF;

• Thiscodefromadatabasetrigger(indicatedby":NEW")showsatypical(andtypicallyproblematic)usageofRAISE_APPLICATION_ERROR.– It'sabusinessrulerequiringa"business"message.

• Typicallyproblematic:– Hard-codingoferrorcodeandmessage– Duplicationof"rule"information:18years.

employee_must_be_18.sqlLivesql.oracle.com search"raise_application_error"


RAISE_APPLICATION_ERRORDetails

• DefinedintheDBMS_STANDARDpackage.• Thenum argumentrange:-20,999and-20,000.

– Usesomethingelseandlose theerrormessage!

• Errormessagescanbeupto2048bytes*.– Youcanpasstoastringofupto32Kbytes,butyouwon'tbeabletogetit"out";youruserswillnotbeabletoseethefullstring.

• Thirdargumentdeterminesifthefullstack oferrorsisreturnedorjustthemostrecent.

RAISE_APPLICATION_ERROR (num binary_integer

, msg varchar2, keeperrorstack boolean default FALSE);

raise_application.sqlmax_rae_string_length.sql

errorstack.sql


HandlingExceptions• TheEXCEPTIONsectionconsolidatesallerrorhandlinglogicinablock.

– Butonlytrapserrorsraisedintheexecutablesectionoftheblock.

• Severalusefulfunctionsusuallycomeintoplay:– SQLCODEandSQLERRM– DBMS_UTILITY.FORMAT_CALL_STACK– DBMS_UTILITY.FORMAT_ERROR_STACK– DBMS_UTILITY.FORMAT_ERROR_BACKTRACE– Plus,newto12.1,theUTL_CALL_STACKpackage

• TheDBMS_ERRLOGpackage–QuickandeasyloggingofDMLerrors


SQLCODEandSQLERRM• SQLCODEreturnstheerrorcodeofthemostrecently-raisedexception.

– YoucannotcallitinsideanSQLstatement(eveninsideaPL/SQLblock).

• SQLERRMisagenericlookupfunction:returnthemessagetextforanerrorcode.– Andifyoudon'tprovideanerrorcode,SQLERRMreturnsthemessageforSQLCODE.

• But....SQLERRMmighttruncatethemessage.– Verystrange,butitispossible.– SoOraclerecommendsthatyounot usethisfunction.

sqlerrm.sqllivesql.oracle.com search"sqlerrm"


DBMS_UTILITY.FORMAT_CALL_STACK• The"callstack"revealsthepath takenthroughyourapplicationcodetogettothatpoint.

• Veryusefulwhenevertracingorloggingerrors.• Thestringisformattedtoshowlinenumberandprogramunitname.

– Butitdoesnotrevealthenamesofsubprograms inpackages.

callstack.sqlcallstack.pkg

livesql.oracle.com search"call_stack"


DBMS_UTILITY.FORMAT_ERROR_STACK• Thisbuilt-inreturnstheerrorstack inthecurrentsession.

– Possiblymorethanoneerrorinstack.

• ReturnsNULLwhenthereisnoerror.• Returnsastringofmaximumsize2000bytes(accordingtothedocumentation).

• OraclerecommendsyouusethisinsteadofSQLERRM,toreducethechanceoftruncation.

errorstack.sqlbig_error_stack.sql

livesql.oracle.com search"error_stack"


DBMS_UTILITY.FORMAT_ERROR_BACKTRACE• Thebacktrace functionanswersthequestion:"Wherewasmyerrorraised?

– Priorto10.2,youcouldnotgetthisinformationfromwithinPL/SQL.

• Callitwheneveryouarelogginganerror.• Whenyoure-raiseyourexception(RAISE;)orraiseadifferentexception,subsequentBACKTRACEcallswillpointtothat line.– Sobeforeare-raise,callBACKTRACEandstorethatinformationtoavoidlosingtheoriginallinenumber.

backtrace.sqlbt.pkg

livesql.oracle.com search"backtrace"

18


OrUseUTL_CALL_STACK(12.1andhigher)• ThisnewpackageprovidesagranularAPItothecallstackandbacktrace.• Italsonowprovidescompletenameinformation,downtothenestedsubprogram.

• Butthebottomlineisthatgenerallyyouwillcallyourfunctionsintheexceptionsection(thruagenericerrorloggingprocedure,Ihope!)andthenwritethatinformationtoyourerrorlog.

• Whenyouneedtodiagnoseanerror,gotothelog,grabthestring,andanalyze.

12c_utl_call_stack*.sqlliveSQL.oracle.com search"utl_call_stack"


ContinuingPastExceptions• Whatifyouwanttocontinueprocessinginyourprogramevenifanerrorhasoccurred?

• Threeoptions...– Useanestedblock– FORALLwithSAVEEXCEPTIONS– DBMS_ERRLOG

continue_past_exception.sql


ExceptionhandlingandFORALL• WhenanexceptionoccursinaDMLstatement....

– ThatstatementisrolledbackandtheFORALLstops.– All(previous)successfulstatementsarenot rolledback.

• UsetheSAVEEXCEPTIONSclausetotellOracletocontinuepast exceptions,andsavetheexceptioninformationforlater.

• Thencheckthecontentsofthepseudo-collectionofrecords,SQL%BULK_EXCEPTIONS.– Twofields:ERROR_INDEXandERROR_CODE


FORALLwithSAVEEXCEPTIONS

• Suppress errors at the statement level.CREATE OR REPLACE PROCEDURE load_books (books_in IN book_obj_list_t)ISbulk_errors EXCEPTION;PRAGMA EXCEPTION_INIT ( bulk_errors, -24381 );

BEGINFORALL indx IN books_in.FIRST..books_in.LASTSAVE EXCEPTIONS

INSERT INTO book values (books_in(indx));EXCEPTION

WHEN bulk_errors THENFOR indx in 1..SQL%BULK_EXCEPTIONS.COUNTLOOP

log_error (SQL%BULK_EXCEPTIONS(indx).ERROR_CODE);END LOOP;

END;

Allows processing of all statements, even after an error

occurs.

Iterate through pseudo-collection of errors.

bulkexc.sqllivesql.oracle.com search "save_exceptions"


LOGERRORSandDBMS_ERRLOG• Usethispackage(addedinOracleDatabase10gRelease2)toenablerow-levelerrorlogging(andexceptionsuppression)forDMLstatements.– ComparetoFORALLSAVEEXCEPTIONS,whichsuppressesexceptionsatthestatementlevel.

• Createsalogtabletowhicherrorsarewritten.– Letsyouspecifymaximumnumberof"toignore"errors.

• Betterperformancethantrapping,loggingandcontinuingpastexceptions.– Exceptionhandlingisslow.

dbms_errlog.sqldbms_errlog_helper.pkg

dbms_errlog_vs_save_exceptions.sqllivesql.oracle.comsearch"logerrors"


LOGERRORSandDBMS_ERRLOG• SuppressDMLrow-levelerrors!• ImpactoferrorsonDMLexecution• IntroductiontoLOGERRORSfeature• Creatinganerrorlogtable• AddingLOGERRORStoyourDMLstatement• "Gotchas"intheLOGERRORSfeature• TheDBMS_ERRLOGhelperpackage


ImpactoferrorsonDMLexecution• AsingleDMLstatement canresultinchangestomultiplerows.• Whenanerroroccursonachangetoarow....

– Allpreviouschangesfromthatstatementarerolledback.– Nootherrowsareprocessed.– Anerrorispassedouttothecallingblock(turnsintoaPL/SQLexception).– NorollbackoncompletedDMLinthatsession.

• Usually acceptable,butwhatifyouwantto:– Avoidlosingallpriorchanges?– AvoidtheperformancepenaltyofexceptionmanagementinPL/SQL?

errors_and_dml.sqllivesql.oracle.comsearch"ExceptionsDoNotRollback"


Row-levelErrorSuppressioninDMLwithLOGERRORS• OncetheerrorpropagatesouttothePL/SQLlayer,itistoolate;allchangestorowshavebeenrolledback.

• TheonlywaytopreservechangestorowsistoaddtheLOGERRORSclauseinyourDMLstatement.– ErrorsaresuppressedatrowlevelwithintheSQLLayer.

• ButyouwillfirstneedtocreatedanerrorlogtablewithDBMS_ERRLOG.


TerminologyforLOGERRORSfeature• DMLtable:thetableonwhichDMLoperationswillbeperformed• Errorloggingtable(aka,errortable):thetablethatwillcontainhistoryoferrorsforDMLtable

• Rejectlimit:themaximumnumberoferrorsthatareacceptableforagivenDMLstatement– "Ifmorethan100errorsoccur,somethingisbadlywrong,juststop."


Step1.Createanerrorlogtable• CallDBMS_ERRLOG.CREATE_ERROR_LOGtocreatetheerrorloggingtableforyour"DMLtable."– Defaultname:ERR$_<your_table_name>

• Youcanspecifyalternativetablename,tablespace,owner.– NecessaryifDMLtablename>25characters!

• ThelogtablecontainsfivestandarderrorloginfocolumnsandthenacolumnforeachVARCHAR2-compatiblecolumnintheDMLtable.

dbms_errlog.sql


Step2:AddLOGERRORStoyourDML

• SpecifythelimitoferrorsafterwhichyouwanttheDMLstatementtostop– orUNLIMITEDtoallowittorunitscourse.

• Then...makesuretochecktheerrorlogtableafteryourunyourDMLstatement!–Oraclewillnot raiseanexceptionwhentheDMLstatementends– bigdifferencefromSAVEEXCEPTIONS.

UPDATE employeesSET salary = salary_in

LOG ERRORS REJECT LIMIT UNLIMITED;

UPDATE employeesSET salary = salary_in

LOG ERRORS REJECT LIMIT 100;


"Gotchas"intheLOGERRORSfeature• Thedefaulterrorloggingtableismissingsomecriticalinformation.

–Whentheerroroccurred,whoexecutedthestatement,whereitoccurredinmycode

• Errorreportingisoftenobscure:"Tableorviewdoesnotexist."• It’suptoyoutograntthenecessaryprivilegesontheerrorlogtable.

– Ifthe“DMLtable”ismodifiedfromanotherschema,thatschemamustbeabletowritetothelogtableaswell.

• UsetheDBMS_ERRLOGhelperpackagetogetaroundmanyoftheseissues.


TheDBMS_ERRLOGhelperpackage• Createstheerrorlogtable.• Addsthreecolumnstokeeptrackofuser,timestampandlocationincode.• Compilesatriggertopopulatetheaddedcolumns.• Createsapackagetomakeiteasiertomanagethecontentsoftheerrorlogtable.

dbms_errlog_helper.sqldbms_errlog_helper_demo.sql

livesql.oracle.comsearch"helperpackage"


LOGERRORS- Conclusions

• WhenexecutingmultipleDMLstatementsoraffectingmultiplerows,decideonyourerrorpolicy.– Stopatfirsterrororcontinue?

• Thendecideonthelevelofgranularityofcontinuation:statementorrow?– LOGERRORSistheonlywaytoperformrow-levelerrorsuppression.

• Makesurethatyoucheckandmanageanyerrorlogscreatedbyyourcode.


SomeRecommendationsforErrorManagement

• Setstandardsbeforeyoustartcoding– It'snotthekindofthingyoucaneasilyaddinlater

• Alwayscallalogprocedureinyourexceptionhandler.– Andeveryoneshouldusethesame logprocedure!

• Decidewhereinthestackyouhandleexceptions.– Alwaysattoplevelblocktoensurethatusersdon'tseeuglyerrormessags.– Ifyouneedtologlocalblockstate,handleinthatblockandre-raise.

• Justuselogger.https://github.com/OraOpenSource/Logger


Alwayscallalogprocedureinyourexceptionhandler

• Alwayslogerrorstoatable.• Neverinsertintoyourlogtableinthehandler.• Everyoneusesthesameprocedure.• Avoidmultipleloggingsforthesameerror.


Decidewhereinthestackyouhandleexceptions.

• Somesuggestthatonlythetop-levelblockshouldtrapanexception.– Theerrorutilityfunctions"remember"whereitcamefrom.

• Butyouloseinformationabouttheapplicationstateatthemomenttheexceptionwasraised.

• WhatIdo:– Alwayshandleattoplevelblocktoensurethatusersdon'tseeuglyerrormessags.– IfIneed tologlocalblockstate(parameters,variables,etc.),Ihandleinthatblockandre-raise.


ErrorManagementSummary• Exceptionsraisedinthedeclarationsectionalwaysescapeunhandled.

– Considerassigningdefaultvaluesintheexecutablesectioninstead.

• CallDBMS_UTILITYorUTL_CALL_STACKfunctionswheneveryouareloggingerrorsandtracingexecution.

• SuppresserrorsatstatementlevelwithFORALL-SAVEEXCEPTIONS• SuppresserrorsatrowlevelwithLOG_ERRORS

– Butdon'tusetheERR$table"asis".

• Relyonastandard,reusableerrorloggingutility.

Error Management Features of PLSQL - dryfta-assets.s3 ... · Copyright © 2018Oracle and/or its...

Documents

Transcript of Error Management Features of PLSQL - dryfta-assets.s3 ... · Copyright © 2018Oracle and/or its...