EachSPUFImessagecontains thefollowing:
v TheSQLCODE,if thestatementexecutessuccessfully.
v TheformattedSQLCA,if thestatementexecutesunsuccessfully.
v WhatcharacterpositionsoftheinputdatasetthatSPUFIscannedtofindSQL statements.Thisinformationhelpsyoucheck theassumptionsthatSPUFImade aboutthelocationoflinenumbers(if any)inyour inputdataset.
v Someoverallstatistics:
– Numberof SQLstatementsthatareprocessed
– Numberof inputrecordsthatareread (fromtheinputdataset) – Numberof outputrecordsthatarewritten (totheoutputdataset).
Other messagesthatyoucouldreceivefromtheprocessingofSQLstatements include:
v ThenumberofrowsthatDB2processed,thateither:
– Yourselectoperationretrieved – Yourupdateoperationmodified – Yourinsertoperationaddedtoa table – Yourdeleteoperationdeletedfromatable
v Whichcolumnsdisplaytruncateddatabecausethedatawastoowide
|
|
|
|
|
|
|
|
Part 2. Coding SQL in your host application program
Chapter6.BasicsofcodingSQLinan
applicationprogram . . . 99 ConventionsusedinexamplesofcodingSQL
statements . . . 100 DelimitinganSQLstatement . . . 100 Declaringtableandviewdefinitions. . . 101 Accessingdatausinghostvariables,hostvariable arrays,andstructures . . . 101
UsinghostvariablesinanSQLstatement . . . 102 Retrievingasinglerowofdataintohost
variables . . . 103 Updatingdatausingvaluesinhostvariables 104 Insertingdatafromcolumnvaluesthatuse hostvariables . . . 105 Usingindicatorvariableswithhostvariables 105 Assignmentsandcomparisonsusingdifferent datatypes . . . 107 ChangingthecodedcharactersetIDofhost variables . . . 107 HostvariablearraysinanSQLstatement . . . 108
Retrievingmultiplerowsofdataintohost variablearrays . . . 109 Insertingmultiplerowsofdatafromhost
variablearrays . . . 109 Usingindicatorvariablearrayswithhost
variablearrays . . . 110 UsinghoststructuresinanSQLstatement. . . 112
Retrievingasinglerowofdataintoahost structure . . . 112 Usingindicatorvariableswithhoststructures 113 CheckingtheexecutionofSQLstatements. . . . 113 UsingtheSQLcommunicationarea(SQLCA) 114 SQLCODEandSQLSTATE . . . 114 TheWHENEVERstatement . . . 115 Handlingarithmeticorconversionerrors . . . 116 TheGETDIAGNOSTICSstatement . . . 116 Retrievingstatementandconditionitems . . 117 DatatypesforGETDIAGNOSTICSitems 118 CallingDSNTIARtodisplaySQLCAfields . . 121 Definingamessageoutputarea . . . 122 PossiblereturncodesfromDSNTIAR . . . 123 PreparingtouseDSNTIAR. . . 123 AscenarioforusingDSNTIAR . . . 124
Chapter7.Usingacursortoretrieveasetof
rows . . . 125 Accessingdatabyusingarow-positionedcursor 125 Step1:Declarethecursor . . . 125 Step2:Openthecursor . . . 127 Step3:Specifywhattodoatend-of-data . . . 128 Step4:ExecuteSQLstatements . . . 128 UsingFETCHstatements . . . 128 UsingpositionedUPDATEstatements . . . 129 UsingpositionedDELETEstatements . . . 129 Step5:Closethecursor . . . 130 Accessingdatabyusingarowset-positionedcursor 130
Step1:Declaretherowsetcursor. . . 130 Step2:Opentherowsetcursor . . . 131 Step3:Specifywhattodoatend-of-datafora rowsetcursor . . . 131 Step4:ExecuteSQLstatementswitharowset cursor . . . 131
Usingamultiple-rowFETCHstatementwith hostvariablearrays . . . 131 Usingamultiple-rowFETCHstatementwith adescriptor . . . 132 Usingrowset-positionedUPDATEstatements 133 Usingrowset-positionedDELETEstatements 134 Numberofrowsinarowset . . . 135 Step5:Closetherowsetcursor . . . 135 AccessingXMLandLOBdatausingFETCHWITH CONTINUE . . . 135
FETCHWITHCONTINUEusingdynamic
bufferallocation . . . 136 FETCHWITHCONTINUEusingfixedbuffer allocation. . . 136 Typesofcursors . . . 138 Scrollableandnon-scrollablecursors . . . . 138 Usinganon-scrollablecursor . . . 138 Usingascrollablecursor . . . 138 Comparisonofscrollablecursors . . . 143 Holesintheresulttableofascrollablecursor 144 Heldandnon-heldcursors . . . 147 Examplesofusingcursors . . . 149
Chapter8.Generatingdeclarationsforyour
tablesusingDCLGEN . . . 155 InvokingDCLGENthroughDB2I . . . 156 Includingthedatadeclarationsinyourprogram 159 DCLGENsupportofC,COBOL,andPL/I
languages . . . 160 Example:Addingatabledeclarationand
host-variablestructuretoalibrary . . . 161 Step1.SpecifyCOBOLasthehostlanguage . . 161 Step2.Createthetabledeclarationandhost
structure . . . 162 Step3.Examinetheresults. . . 164
Chapter9.EmbeddingSQLstatementsinhost languages . . . 167 CodingSQLstatementsinanassemblerapplication 167
DefiningtheSQLcommunicationsareain
assembler . . . 167 IfyouspecifySTDSQL(YES) . . . 167 IfyouspecifySTDSQL(NO) . . . 168 DefiningSQLdescriptorareasinassembler . . 168 EmbeddingSQLstatementsinassembler . . . 169 Hostvariablesinassembler . . . 171 Declaringhostvariablesinassembler . . . . 171 EquivalentSQLandassemblerdatatypes . . . 175
Notesonassemblervariabledeclarationand usage . . . 180
|
|
|
|
|
|
|
|
|
CompatibilityofSQLandassemblerdatatypes 181 Indicatorvariablesinassembler . . . 182 HandlingSQLerrorreturncodesinassembler 183 Macrosforassemblerapplications . . . 184 CodingSQLstatementsinaCorC++application 185
DefiningtheSQLcommunicationareainCor C++ . . . 185
IfyouspecifySTDSQL(YES) . . . 185 IfyouspecifySTDSQL(NO) . . . 185 DefiningSQLdescriptorareasinCorC++ . . 186 EmbeddingSQLstatementsinCorC++ . . . 186 HostvariablesandhostvariablearraysinCor C++ . . . 188
PointersashostvariablesinCorC++ . . . 189 DeclaringhostvariablesinCorC++ . . . . 190 NumerichostvariablesinCorC++. . . . 191 CharacterhostvariablesinCorC++ . . . 191 GraphichostvariablesinCorC++ . . . . 193 BinaryhostvariablesinCorC++ . . . . 195 ResultsetlocatorsinCorC++ . . . 196 TablelocatorsinCorC++ . . . 196 LOBvariablesandlocatorsinCorC++ . . 197 XMLdatahostandfilereferencevariablesin CorC++. . . 198 ROWIDsinCorC++ . . . 199 DeclaringhostvariablearraysinCorC++ . . 199 NumerichostvariablearraysinCorC++ 199 CharacterhostvariablearraysinCorC++ 200 BinaryhostvariablearraysinCorC++ . . 202 GraphichostvariablearraysinCorC++ . . 202 LOB,locator,filereference,andXMLvariable arraysinCorC++ . . . 204 ROWIDvariablearraysinCorC++. . . . 205 HoststructuresinCorC++ . . . 206 EquivalentSQLandCdatatypes. . . 208 NotesonCvariabledeclarationandusage 212 Notesonsyntaxdifferencesforconstantsin CorC++. . . 215 CompatibilityofSQLandCdatatypes. . . . 215 Indicatorvariablesandindicatorvariablearrays inCorC++ . . . 217 HandlingSQLerrorreturncodesinCorC++ 218 CodingSQLstatementsinaCOBOLapplication 220
DefiningtheSQLcommunicationareain
COBOL . . . 220 IfyouspecifySTDSQL(YES) . . . 221 IfyouspecifySTDSQL(NO) . . . 221 DefiningSQLdescriptorareasinCOBOL . . . 221 EmbeddingSQLstatementsinCOBOL. . . . 222 Hostvariablesandhostvariablearraysin
COBOL . . . 226 DeclaringhostvariablesinCOBOL . . . 226 Numerichostvariables . . . 227 Characterhostvariables. . . 228 Graphiccharacterhostvariables . . . 230 Binaryhostvariables . . . 232 Resultsetlocators . . . 232 TableLocators . . . 233 LOBvariablesandfilereferencevariables 233 ROWIDs . . . 234 DeclaringhostvariablearraysinCOBOL . . . 234
HoststructuresinCOBOL . . . 242 EquivalentSQLandCOBOLdatatypes . . . 247
NotesonCOBOLvariabledeclarationand usage . . . 251 CompatibilityofSQLandCOBOLdatatypes 254 Indicatorvariablesandindicatorvariablearrays inCOBOL . . . 255 HandlingSQLerrorreturncodesinCOBOL . . 257 Object-orientedextensionsinCOBOL . . . . 258 CodingSQLstatementsinaFortranapplication 259
DefiningtheSQLcommunicationareain
Fortran . . . 259 IfyouspecifySTDSQL(YES) . . . 259 IfyouspecifySTDSQL(NO) . . . 259 DefiningSQLdescriptorareasinFortran . . . 260 EmbeddingSQLstatementsinFortran . . . . 260 HostvariablesinFortran . . . 262 DeclaringhostvariablesinFortran . . . 262 EquivalentSQLandFortrandatatypes. . . . 264
NotesonFortranvariabledeclarationand usage . . . 265 Notesonsyntaxdifferencesforconstants . . 266 CompatibilityofSQLandFortrandatatypes 267 IndicatorvariablesinFortran . . . 267 HandlingSQLerrorreturncodesinFortran . . 268 CodingSQLstatementsinaPL/Iapplication . . 269 DefiningtheSQLcommunicationareainPL/I 269 IfyouspecifySTDSQL(YES) . . . 269 IfyouspecifySTDSQL(NO) . . . 269 DefiningSQLdescriptorareasinPL/I . . . . 270 EmbeddingSQLstatementsinPL/I. . . 270 HostvariablesandhostvariablearraysinPL/I 273 DeclaringhostvariablesinPL/I . . . 273 Numerichostvariables . . . 274 Characterhostvariables. . . 274 Graphichostvariables . . . 274 Binaryhostvariables . . . 275 Resultsetlocators . . . 276 Tablelocators . . . 276 LOBvariables,locators,andfilereference
variables . . . 276 ROWIDs . . . 277 DeclaringhostvariablearraysinPL/I . . . . 278 HoststructuresinPL/I . . . 282 EquivalentSQLandPL/Idatatypes . . . . 284
NotesonPL/Ivariabledeclarationand
usage . . . 287 CompatibilityofSQLandPL/Idatatypes . . 288 Indicatorvariablesandindicatorvariablearrays inPL/I . . . 290 HandlingSQLerrorreturncodesinPL/I . . . 291 CodingSQLstatementsinaREXXapplication . . 293 DefiningtheSQLcommunicationareainREXX 293 DefiningSQLdescriptorareasinREXX. . . . 293 AccessingtheDB2REXXLanguageSupport
applicationprogramminginterfaces . . . 294 EmbeddingSQLstatementsinaREXX
procedure . . . 295 CursorsandstatementnamesinREXX. . . . 297 REXXhostvariablesanddatatypes . . . 297
||
||
||
|
|
DeterminingequivalentSQLandREXXdata types . . . 297 LettingDB2determinetheinputdatatype 298 EnsuringthatDB2correctlyinterprets
characterinputdata . . . 299 Passingthedatatypeofaninputvariableto DB2 . . . 299 RetrievingdatafromDB2tables . . . 300 IndicatorvariablesinREXX . . . 301 SettingtheisolationlevelofSQLstatementsina REXXprocedure . . . 302
Chapter10.Maintainingdataintegritybyusing constraints. . . 303 Checkconstraints . . . 303 Checkconstraintconsiderations . . . 303 Whencheckconstraintsareenforced . . . . 304 HowcheckconstraintssetCHECK-pending
status . . . 304 Referentialconstraints . . . 305 Parentkeycolumns . . . 305 Definingaparentkeyandauniqueindex. . . 306 Incompletetabledefinition . . . 307 Recommendationsfordefiningprimarykeys 308 Definingaforeignkey . . . 308 Therelationshipname . . . 308 Indexesonforeignkeys . . . 309 TheFOREIGNKEYclauseinALTERTABLE 309 Restrictionsoncyclesofdependenttables 309 Maintainingreferentialintegritywhenusing dataencryption. . . 310 Referentialconstraintsontableswithmultilevel securitywithrow-levelgranularity . . . 310 Usinginformationalreferentialconstraints. . . . 311
Chapter11.UsingDB2-generatedvaluesas
keys . . . 313 ROWIDcolumnsaskeys . . . 313 DefiningaROWIDcolumn. . . 313 SpecifyingdirectrowaccessbyusingaROWID column . . . 314 SpecifyingdirectrowaccessbyusingRIDs . . . 314 Usingidentitycolumnsaskeys . . . 315 Defininganidentitycolumn . . . 315 Identitycolumnsasprimarykeys . . . 316 Usingvaluesobtainedfromsequenceobjectsas
keys . . . 317 Creatingasequenceobject . . . 318 Referencingasequenceobject . . . 318 Keysacrossmultipletables. . . 318
Chapter12.Usingtriggersforactivedata . . . 321 Exampleofcreatingandusingatrigger . . . . 321 Partsofatrigger . . . 323 Triggername . . . 323 Subjecttable. . . 323 Triggeractivationtime . . . 323 Triggeringevent . . . 323 Granularity . . . 324 Transitionvariables . . . 325 Transitiontables . . . 326
Triggeredaction . . . 327 Triggercondition . . . 327 Triggerbody . . . 327 Invokingstoredproceduresanduser-defined
functionsfromtriggers . . . 329 Passingtransitiontablestouser-definedfunctions andstoredprocedures . . . 329 Triggercascading . . . 330 Orderingofmultipletriggers . . . 331 Inserting,updating,anddeletingdatainviewsby usingINSTEADOFtriggers . . . 331 Interactionsbetweentriggersandreferential
constraints . . . 333 Interactionsbetweentriggersandtablesthathave multilevelsecuritywithrow-levelgranularity . . 334 Creatingtriggerstoobtainconsistentresults . . . 335
||
||
|
|
|
Chapter 6. Basics of coding SQL in an application program
Supposeyouare writinganapplicationprogramtoaccessdatainaDB2database.
WhenyourprogramexecutesanSQLstatement,theprogramneedsto
communicatewithDB2.WhenDB2finishesprocessinganSQLstatement, DB2 sendsbackareturn code,and yourprogramshouldtestthereturncodeto examinetheresultsoftheoperation.
TocommunicatewithDB2,youneedtoperformthefollowingactions:
v Chooseamethod forcommunicatingwith DB2.Youcanuseoneofthe followingmethods:
– StaticSQL
– Embedded dynamicSQL
– OpenDatabaseConnectivity(ODBC) – JDBC applicationsupport
– SQLJapplicationsupport
ThisinformationdiscussesembeddedSQL.SeeChapter25,“Codingdynamic SQLinapplicationprograms,” onpage661 foracomparisonofstaticand embeddeddynamicSQLandan extendeddiscussionofembedded dynamic SQL.
ODBCletsyouaccessdatathroughODBCfunction callsinyourapplication.
YouexecuteSQLstatementsbypassingthemtoDB2througha ODBCfunction call.ODBCeliminatestheneedforprecompilingand bindingyour application andincreasestheportabilityofyourapplicationbyusingtheODBCinterface.
Ifyouarewritingyour applicationsinJava™,youcanuseJDBCapplication supporttoaccessDB2.JDBCissimilartoODBCbutisdesigned specificallyfor usewith Java.Inaddition tousingJDBC,youcanuseSQLJapplicationsupport toaccessDB2.SQLJisdesignedtosimplifythecodingofDB2calls forJava applications.For moreinformationaboutwritingJDBC applications,seethe topic“ProgrammingJDBCapplications”inDB2ApplicationProgrammingGuide andReferenceforJava.FormoreinformationaboutwritingSQLJapplications,see thetopic“ProgrammingSQLJapplications”inDB2 ApplicationProgramming Guideand ReferenceforJava.
v DelimitSQLstatements,asdescribedin “DelimitinganSQLstatement”onpage 100.
v Declarethetablesthatyouuse, asdescribed in“Declaringtableandview definitions”onpage101.(Thisisoptional.)
v DeclarethedataitemsforpassingdatabetweenDB2anda hostlanguage, accordingtothehostlanguagerulesdescribedinChapter9,“EmbeddingSQL statementsinhostlanguages,”onpage167.
v
CodeSQLstatementstoaccessDB2data.See“Accessingdatausinghost variables,hostvariable arrays,andstructures”onpage101.
ForinformationabouthowtousetheSQLlanguage,seePart1,“SQLqueries,”
onpage1. ForinformationabouthowtouseSQLstatementswithinapplication programs,seeChapter9,“EmbeddingSQLstatementsinhostlanguages,” on page167.
v DeclareanSQLcommunicationsarea(SQLCA).Alternatively,youcanusethe GETDIAGNOSTICS statementto providediagnostic informationaboutthelast SQLstatementthatexecuted.See“Checking theexecutionofSQLstatements”
onpage113formoreinformation.
Inadditiontothese basicrequirements,youshouldalso considerthefollowing special topics:
v Cursors—Chapter7, “Usinga cursortoretrieveaset ofrows,”onpage125 discusseshow tousea cursorinyourapplication programtoselectaset ofrows andthenprocess theset eitheronerowat atimeoronerowsetatatime.
v DCLGEN—Chapter8, “Generatingdeclarationsforyourtablesusing DCLGEN,”onpage155discusseshow touseDB2’sdeclarationsgenerator, DCLGEN,toobtainaccurateSQLDECLAREstatementsfortablesandviews.
ThistopicincludesinformationaboutusingSQLinapplicationprogramswritten in assembler,C, C++,COBOL,Fortran,PL/I, andREXX.