Held and non-held cursors
Chapter 8. Generating declarations for your tables using DCLGEN
DCLGEN,thedeclarationsgeneratorsuppliedwithDB2,producesa DECLARE statementyoucanuseina C,COBOL,orPL/Iprogram, sothatyoudonotneed tocode thestatementyourself.Forinformationaboutthesyntaxof DCLGEN,see thetopic“DCLGEN(DECLARATIONSGENERATOR)(DSN)” inDB2Command Reference.
DCLGEN generatesatable declarationandputsit intoamemberofa partitioned dataset thatyoucanincludeinyour program.WhenyouuseDCLGENto generatea table’sdeclaration,DB2 getstherelevantinformationfromtheDB2 catalog,whichcontains informationaboutthetable’sdefinitionandthedefinition of eachcolumnwithinthetable.DCLGENusesthisinformationtoproducea completeSQLDECLAREstatementforthetableorview andacorresponding PL/I,Cstructuredeclaration,or COBOLrecord description.YoucanuseDCLGEN fortable declarationsonlyifthetableyouaredeclaringalreadyexists.
Youmust useDCLGEN beforeyouprecompileyour program.Supplythetableor view nametoDCLGEN beforeyouprecompileyour program.Tousethe
declarationsgeneratedbyDCLGENinyourprogram, usetheSQLINCLUDE statement. FormoreinformationabouttheINCLUDEstatement,seethetopic
“INCLUDE”inDB2SQLReference.
DB2 mustbe activebefore youcanuseDCLGEN.Youcanstart DCLGENin severaldifferentways:
v FromISPFthrough DB2I.SelecttheDCLGEN optionontheDB2IPrimary OptionMenu panel.
v
DirectlyfromTSO.Todothis,signontoTSO,issue theTSOcommandDSN, andthenissue thesubcommand DCLGEN.
v FromaCLIST, runningin TSOforegroundorbackground, thatissuesDSNand thenDCLGEN.
v WithJCL.Supplytherequiredinformation,usingJCL, andrunDCLGENin batch.Intheprefix.SDSNSAMPlibrary,samplejobsDSNTEJ2CandDSNTEJ2P showhow touseJCLtorunDCLGEN.Formore informationaboutthesyntax oftheDSNsubcommand DCLGEN,seethetopic“DCLGEN(DECLARATIONS GENERATOR)(DSN)”inDB2 CommandReference.
IfyouwanttostartDCLGEN intheforeground,andyour tablenamesinclude DBCScharacters,youmust provideanddisplaydouble-bytecharacters.Ifyou donothavea terminalthatdisplaysDBCScharacters,youcanenterDBCS charactersusingthehexmodeofISPFedit.
Thistopicincludesthefollowinginformation:
v “InvokingDCLGEN throughDB2I”onpage156
v “Includingthedatadeclarationsinyourprogram”onpage159 v “DCLGENsupport ofC,COBOL,and PL/Ilanguages”onpage160
v “Example:Adding atabledeclaration andhost-variablestructure toalibrary”
onpage161
Invoking DCLGEN through DB2I
The easiestway tostartDCLGENisthroughDB2I.Figure24showstheDCLGEN panelyoureachbyselectingtheDCLGENoptionontheDB2IPrimaryOption Menu panel.Formore instructionsonusingDB2I,see“Preparingapplicationsby theDB2ProgramPreparationpanels”onpage587.
Fill intheDCLGENpanelasfollows:
1 SOURCETABLENAME
Is theunqualifiednameofthetable,view,orcreatedtemporarytablefor whichyouwantDCLGEN toproduceSQLdatadeclarations.Thetablecan be storedatyour DB2locationoratanotherDB2location.Tospecifya tablenameatanotherDB2 location,enterthetablequalifierintheTABLE OWNER fieldandthelocationnameintheATLOCATIONfield.DCLGEN generatesa three-parttablenamefromtheSOURCETABLENAME, TABLEOWNER, andATLOCATIONfields.Youcanalsouseanaliasfora tablename.
Tospecifya tablenamethatcontains specialcharactersorblanks,enclose thenameinapostrophes.Ifthenamecontainsapostrophes,youmust doubleeachone(’ ’).Forexample,tospecifyatablenamedDON’STABLE, enterthefollowing:
’DON’’S TABLE’
YoudonotneedtoencloseDBCStablenamesinapostrophes.Ifyoudo notenclosethetable nameinapostrophes,DB2convertslowercase characters touppercase.
Theunderscoreisnothandledasa specialcharacterinDCLGEN.For example,thetablenameJUNE_PROFITSdoesnotneedtobe enclosedin apostrophes.BecauseCOBOLfieldnamescannotcontainunderscores, DCLGEN substituteshyphens(-)forsingle-byteunderscoresinCOBOL fieldnamesthatarebuiltfromthetablename.
DSNEDP01 DCLGEN SSID: DSN
===>
Enter table name for which declarations are required:
1 SOURCE TABLE NAME ===>
2 TABLE OWNER ... ===>
3 AT LOCATION ... ===> (Optional) Enter destination data set: (Can be sequential or partitioned)
4 DATA SET NAME ... ===>
5 DATA SET PASSWORD ===> (If password protected) Enter options as desired:
6 ACTION ... ===> ADD (ADD new or REPLACE old declaration)
7 COLUMN LABEL .... ===> NO (Enter YES for column label)
8 STRUCTURE NAME .. ===> (Optional)
9 FIELD NAME PREFIX ===> (Optional) 10 DELIMIT DBCS .... ===> YES (Enter YES to delimit DBCS identifiers) 11 COLUMN SUFFIX ... ===> NO (Enter YES to append column name) 12 INDICATOR VARS .. ===> NO (Enter YES for indicator variables) 13 RIGHT MARGIN .... ===> 72 (Enter 72 or 80)
PRESS: ENTER to process END to exit HELP for more information
Figure24.DCLGENpanel
||
||
||
||
||
||
||
||
||
|
||
||
2 TABLEOWNER
Is theschemaqualifierofthesourcetable.Ifyoudo notspecifythisvalue and thetable isa localtable,DB2assumesthatthetable qualifierisyour TSOlogonID.Ifthetableisata remotelocation,youmustspecifythis value.
3 ATLOCATION
Is thelocationofa tableorviewat anotherDB2subsystem.Ifyouspecify this parameter,youmustalso specifyaqualifiednameintheSOURCE TABLENAME field.ThevalueoftheATLOCATION fieldbecomesa prefixforthetablenameontheSQLDECLARE statement,asfollows:
location_name, schema_name, table_name
For example,forthelocationPLAINS_GA:
PLAINS_GA.CARTER.CROP_YIELD_89
Thedefaultisthelocallocationname.ThisfieldappliestoDB2private protocolaccessonly.Thelocationyounamemust beanotherDB2 for z/OS.
4 DATASETNAME
Is thenameofthedatasetyouallocatedtocontainthedeclarationsthat DCLGEN produces.Youmustsupply aname;nodefaultexists.
Thedataset mustalreadyexist,beaccessibletoDCLGEN,and canbe eithersequentialorpartitioned.Ifyoudonotenclosethedatasetnamein apostrophes,DCLGENaddsa standardTSOprefix(user ID)and suffix (language).DCLGENknowswhatthehostlanguageisfromtheDB2I defaults panel.
For example,forlibrarynameLIBNAME(MEMBNAME),thename becomes:
userid.libname.language(membname)
For librarynameLIBNAME,thenamebecomes:
userid.libname.language
Ifthis datasetispasswordprotected, youmust supplythepasswordin theDATASETPASSWORD field.
5 DATASETPASSWORD
Is thepasswordforthedatasetintheDATASETNAMEfield,if thedata set ispasswordprotected.Itisnotdisplayedonyourterminal,andit is notrecognizedifyouissueditfroma previoussession.
6 ACTION
TellsDCLGEN whattodo withtheoutputwhenitissenttoapartitioned dataset.(Theoption isignoredifthedatasetyouspecifyintheDATA SETNAME fieldissequential.)
ADDindicatesthatanoldversion oftheoutputdoesnotexistand createsa newmemberwiththespecifieddatasetname. Thisisthe default.
REPLACEreplacesanoldversion,ifitalreadyexists.Ifthemember doesnotexist, thisoptioncreatesa newmember.
7 COLUMNLABEL
TellsDCLGEN whethertoincludelabelsthataredeclaredonanycolumns
|
|
|
|
ofthetableorview ascommentsinthedatadeclarations.(TheSQL statementLABELcreatescolumnlabelstouseassupplements tocolumn names.)Use:
YEStoincludecolumnlabels.
NOtoignorecolumnlabels.Thisisthedefault.
8 STRUCTURENAME
Is thenameofthegenerateddatastructure.Thenamecanbe upto31 characters.IfthenameisnotaDBCS string,andthefirstcharacterisnot alphabetic,then enclosethenameinapostrophes.Ifyouusespecial characters,be carefultoavoidnameconflicts.
Ifyouleavethis fieldblank,DCLGENgeneratesa namethatcontainsthe tableor viewnamewithaprefixofDCL.IfthelanguageisCOBOLor PL/I,and thetable orviewnameconsistsof aDBCSstring,theprefix consistsofDBCScharacters.
For C,lowercase charactersyouenterinthisfielddo notfoldtouppercase.
9 FIELDNAMEPREFIX
Specifiesa prefixthatDCLGEN usestoformfieldnamesintheoutput.For example,if youchooseABCDE,thefieldnamesgeneratedareABCDE1, ABCDE2, andsoon.
DCLGEN acceptsafieldnameprefixofupto28bytesthatcaninclude special anddouble-bytecharacters.Ifyouspecifyasingle-byteor mixed-stringprefixand thefirst characterisnotalphabetic,apostrophes must enclosetheprefix.Ifyouusespecialcharacters,avoidnameconflicts.
For COBOLandPL/I,ifthenameisa DBCSstring,DCLGENgenerates DBCS equivalentsofthesuffixnumbers.For C,lowercasecharacters you enterinthisfielddo notfoldtouppercase.
Ifyouleavethis fieldblank,thefieldnamesare thesameasthecolumn namesinthetableorview.
10DELIMIT DBCS
TellsDCLGEN whethertodelimitDBCStable namesand columnnamesin thetabledeclaration.Use:
YEStoenclosetheDBCStableand columnnameswithSQLdelimiters.
NOtonotdelimittheDBCStableand columnnames.
11 COLUMNSUFFIX
TellsDCLGEN whethertoformfieldnamesbyattaching thecolumnname asa suffixtothevalueyouspecifyinFIELD NAMEPREFIX.For example, if youspecifyYES,thefieldnameprefixisNEW,andthecolumnnameis EMPNO, thefieldnameisNEWEMPNO.
IfyouspecifyYES,youmustalsoentera valueinFIELDNAME PREFIX.
Ifyoudonotenterafieldnameprefix,DCLGEN issuesa warning messageand usesthecolumnnamesasthefieldnames.
ThedefaultisNO,whichdoesnotusethecolumnnameasa suffixand allows thevalue inFIELDNAMEPREFIXtocontrolthefieldnames,if specified.
12INDICATORVARS
TellsDCLGEN whethertogenerateanarrayofindicatorvariablesforthe hostvariable structure.
IfyouspecifyYES,thearraynameisthetablenamewithaprefixofI(or DBCSletter <I>ifthetablenameconsistssolelyofdouble-bytecharacters).
Theform ofthedatadeclaration dependsonthelanguage:
For a C program: short int Itable-name[n];
For a COBOL program: 01 Itable-name PIC S9(4) USAGE COMP OCCURS n TIMES.
For a PL/I program: DCL Itable-name(n) BIN FIXED(15);
n isthenumberofcolumns inthetable.Forexample,supposeyoudefine thefollowingtable:
CREATE TABLE HASNULLS (CHARCOL1 CHAR(1), CHARCOL2 CHAR(1));
YourequestanarrayofindicatorvariablesforaCOBOLprogram.
DCLGEN mightgeneratethefollowinghostvariabledeclaration:
01 DCLHASNULLS.
10 CHARCOL1 PIC X(1).
10 CHARCOL2 PIC X(1).
01 IHASNULLS PIC S9(4) USAGE COMP OCCURS 2 TIMES.
ThedefaultisNO,whichdoesnotgenerateanindicatorvariable array.
11 RIGHTMARGIN
Specifiesthebreakpointforstatementtokensthatmust bewrappedtoone ormore subsequentrecords.Youcanspecifycolumn72orcolumn80.
Thedefaultis72.
DCLGEN generatesatable orcolumnnameintheDECLAREstatementasa non-delimited identifierunlessatleastoneofthefollowingconditions istrue:
v Thenamecontains specialcharactersandisnotaDBCSstring.
v ThenameisaDBCS string,andyouhaverequesteddelimitedDBCSnames.
IfyouareusinganSQLreservedword asanidentifier,youmusteditthe DCLGEN outputinordertoaddtheappropriateSQLdelimiters.
DCLGEN producesoutputthatisintended tomeettheneedsof mostusers,but occasionally, youwillneedtoedittheDCLGENoutputtoworkinyour specific case. Forexample,DCLGENisunabletodeterminewhetheracolumnthatis definedasNOTNULLalsocontains theDEFAULT clause,soyoumusteditthe DCLGEN outputtoaddtheDEFAULT clausetotheappropriate column definitions.
Including the data declarations in your program
Use thefollowingSQLINCLUDEstatementtoplacethegeneratedtable declaration andCOBOLrecorddescriptioninyoursourceprogram:
EXEC SQL
INCLUDE member-name END-EXEC.
For example,toincludea descriptionforthetableDSN8910.EMP,code:
EXEC SQL
INCLUDE DECEMP END-EXEC.
Inthisexample,DECEMPisa nameof amemberofa partitioneddatasetthat contains thetable declarationanda correspondingCOBOLrecorddescriptionof thetableDSN8910.EMP.(ACOBOLrecorddescriptionisa two-levelhoststructure
|
|
|
|
thatcorresponds tothecolumns ofatable’srow.Forinformationonhost
structures, seeChapter9,“EmbeddingSQLstatements inhostlanguages,”onpage 167.) Togetacurrentdescriptionofthetable,useDCLGEN togeneratethetable’s declaration andstoreitasmemberDECEMPinalibrary(usuallyapartitioned dataset) justbeforeyouprecompiletheprogram.