Xây dựng giao diện lập trình OCI

c tìm thaáy trong taäp kyù töï OTT maëc duø moät kyù töï coù hai maõ khaùc nhau trong hai taäp kyù töï . Caùch deã nhaát ñeå baûo ñaûm raèng taäp kyù töï ñöôïc söû duïng bôûi OTT chöùa taát caû caùc kyù töï caàn thieát laø taïo noù gioáng nhö taäp kyù töï database . Tuy nhieân chuù yù raèng taäp kyù töï OTT phaûi laø sieâu taäp (superset) cuûa taäp kyù töï bieân dòch . Nghóa laø , neáu taäp kyù töï bieân dòch laø ASCII 7-bit thì taäp kyù töï OTT phaûi coù taäp ASCII 7-bit nhö laø taäp con , neáu taäp kyù töï bieân dòch laø taäp EBCDIC 7-bit thì taäp kyù töï OTT phaûi coù taäp naøy nhö laø taäp con . User ñònh roõ taäp kyù töï maø OTT söû duïng baèng caùch thieát laäp NLS_LANG (enviroment variable) hoaëc moätsoá platform-specific mechanism . Moät khi OTT ñoïc teân cuûa phaàn töû database , noù chuyeån ñoåi teân töø taäp kyù töï OTT sang taäp kyù töï cuûa trình bieân dòch . Neáu coù moät söï chuyeån ñoåi teân trong file INTYPE thì OTT söû duïng söï chuyeån ñoåi naøy . Caùch chuyeån ñoåi teân cuûa OTT : ñaàu tieân , neáu taäp kyù töï laø taäp kyù töï nhieàu byte , taát caû caùc kyù töï nhieàu byte (multi-byte character) cuûa teân maø noù töông ñöông vôùi nhieàu byte ñôn ñöôïc chuyeån ñoåi thaønh caùc byte ñôn ñoù . Tieáp theo , teân ñöôïc chuyeån ñoåi töø taäp kyù töï OTT sang taäp kyù töï bieân dòch . Taäp kyù töï bieân dòch byte ñôn nhö laø US7ASCII . Cuoái cuøng , côû chöõ ñöôïc thieát laäp theo tuøy choïn CASE , coøn baát kyø kyù töï khoâng hôïp leä trong moät teân goïi C hoaëc khoâng coù söï chuyeån ñoåi trong taäp kyù töï bieân dòch thì ñöôïc thay baèng '_' . Neáu coù moät kyù töï maø ñöôïc thay baèng '_' thì OTT thoâng baùo loãi . Neáu taát caû caùc kyù töï cuûa teân ñöôïc thay baèng '_' thì OTT thoâng baùo moät loãi . Söï chuyeån ñoåi kyù töï sang kyù töï khoâng thay ñoåi daáu '_' , soá hoaëc caùc kyù töï byte ñôn xuaát hieän trong taäp kyù töï bieân dòch , vì vaäy teân hôïp leä vôùi C khoâng ñöôïc thay ñoåi . Söï chuyeån ñoåi teân , ví duï , chuyeån ñoåi caùc kyù töï byte ñôn laø troïng aâm nhö "o" hoaëc "a" sang "o" hoaëc "a" vaø coù theå chuyeån ñoåi maãu töï nhieàu byte thaønh caùc byte ñôn töông ñöông . Chuyeån ñoåi teân seõ hoûng neáu teân bao goàm nhieàu kyù töï nhieàu byte maø thieáu caùc byte ñôn töông . Trong tröôøng hôïp naøy user seõ ñònh roõ caùc chuyeån ñoåi teân trong file INTYPE . OTT khoâng tìm ra ñöôïc söï maâu thuaãn gaây bôûi hai hoaëc nhieàu teân database ñöôïc aùnh xaï sang cuøng moät teân cuûa C , cuõng khoâng tìm ra moät teân database aùnh xaï thaønh moät töø khoùa cuûa C . 8 . Caùc haïn cheá Moät soá haïn cheá khi söû duïng OTT So saùnh teân file : OTT xaùc ñònh neáu hai file gioáng teân nhau trong command line hoaëc file INTYPE . Nhöng moät vaán ñeà tìm aån coù theå xaûy ra khi OTT caàn bieát neáu hai teân file cuøng chæ ñeán moät file . Ví duï , neáu file foo.h (do OTT taïo ra ) caàn khai baùo kieåu foo1.h vaø moät khai baùo khaùc /private/elias/foo1.h thì OTT seõ taïo ra moät #include neáu hai file gioáng nhau vaø hai #include neáu hai khaùc nhau . Thöïc teá hai file laø khaùc nhau vaø taïo ra hai #include .Theo ñoù neáu moät file ñöôïc ñeà caäp moät vaøi laàn treân command line hoaëc file INTYPE , moãi laàn file ñöôïc söû duïng chính xaùc . CHÖÔNG X : CAÙC HAØM QUAN HEÄ CUÛA OCI I.Giôùi thieäu Chöông naøy moâ taû caùc lôøi goïi haøm OCI , bao goàm caùc haøm cô baûn vaø söï tham chieáu keát hôïp . Danh saùch caùc haøm : CONNECT / INITIALIZE / AUTHORIZE OCIInitialize() Khôûi taïo moâi tröôøng xöû lyù cuûa OCI OCIEnvInit() Khôûi taïo moät environment handle OCIServerAttach() Raøng buoäc ñeán moät server, khôûi taïo context handle cuûa server OCIServerDetach() Thoaùt khoûi raøng buoäc cuûa server; uninitialize server context handle OCISessionBegin() Chaáp nhaän moät user OCISessionEnd() Keát thuùc moät user OCILogon() Ñôn giaûn hoùa single-session logon OCILogoff() Ñôn giaûn hoùa single-session logoff HANDLES / DESCRIPTORS OCIHandleAlloc() Chæ ñònh vaø khôûi taïo moät handle OCIHandleFree() Giaûi phoùng moät handle ñöôïc chæ ñònh tröôùc ñoù OCIAttrGet() Nhaän caùc thuoäc tính cuûa handle OCIParamGet() Nhaän moät tham soá descriptor OCIParamSet() Set parameter descriptor in COR handle OCIAttrSet() Set an attribute of a handle or descriptor OCIDescriptorAlloc() Allocate and initialize a descriptor or LOB locator OCIDescriptorFree() Free a previously allocated descriptor TRANSACTION MANAGEMENT OCITransCommit() Giao dòch uûy thaùc OCITransDetach() Thoaùt khoûi moät giao dòch töø moät ngöõ caûnh phuïc vuï OCITransRollback() Rollback moät transaction OCITransStart() Start a transaction on a service context OCITransPrepare() Chuaån bò moät giao dòch ñeå uûy thaùc OCITransForget() Forget a prepared global transaction BIND OCIBindDynamic() Set additional attributes after bind with OCI_DATA_AT_EXEC mode OCIBindByName Bind by name OCIBindByPos() Bind by position OCIBindObject() Set additional attributes for bind of named data type OCIBindArrayOfStruct() Set skip parameters for static array bind OCIStmtGetBindInfo() Get bind and indicator variable names and handles DEFINE OCIDefineArrayOfStruct() Set additional attributes for static array define OCIDefineDynamic() Set additional attributes for define in OCI_DYNAMIC_FETCH mode OCIDefineByPos() Define an output variable association OCIDefineObject() Set additional attributes for define of named data type DESCRIBE OCIDescribeAny() Describe existing schema objects PREPARE/EXECUTE OCIStmtPrepare() Thieát laäp moät yeâu caàu öùng duïng OCIStmtExecute() Send statements to server for execution FETCH OCIStmtFetch() Fetch rows from a query LOB/FILE OPERATIONS OCILobFileClose() Close a previously opened FILE OCILobFileCloseAll() Close all previously opened files OCILobFileOpen() Open a FILE OCILobAppend() Append to a LOB OCILobCopy() Copy a LOB OCILobErase() Xoùa moät phaàn cuûa moät LOB OCILobGetLength() Get length of a LOB or FILE OCILobRead() Ñoïc moät phaàn cuûa moät LOB hoaëc FILE OCILobTrim() Xeùn bôùt moät LOB OCILobWrite() Write into a LOB OCILobAssign() Assign one LOB locator to another OCILobIsEqual() Compare two LOB locators for Equality OCILobFileGetName() Get directory alias and file NaMe from the LOB locator OCILobFileIsOpen() Check if file on server is open via this locator OCILobFileSetName() Set directory alias and file NaMe in the LOB locator OCILobLocatorIsInit() Check to see if a LOB locator is initialized OCILobCharSetID Get character set ID from LOB locator OCILobCharSetForm() Get character set form from LOB locator OCILobFileExists() Check if a file exists on the server OCILobLoadFromFile() Load a LOB from a FILE OCILobDisableBuffering() Turn LOB buffering off OCILobEnableBuffering() Turn LOB buffering on OCILobFlushBuffer() Flush the LOB buffer MISCELLANEOUS OCIBreak() Perform an immediate asynchronous break OCIServerVersion() Get the Oracle version string OCIPasswordChange() Change password OCIErrorGet() Return error message and Oracle error OCIStmtGetPieceInfo() Get piece information for piecewise operations OCIStmtSetPieceInfo() Set piece information for piecewise operations OCILdaToSvcCtx() Ñöa Lda_Def ñeán service context handle OCISvcCtxToLda() Ñöa service context handle ñeán Lda_Def TYPE INFORMATION ACCESSOR FUNCTIONS OCITypeArrayByName() Get an array of TDOs given an array of object names OCITypeArrayByRef() Get an array of TDOs given an array of object references OCITypeByName() Get a TDO given an object name OCITypeByRef() Get a TDO given an object reference Sau ñaây seõ giôùi thieäu moät soá haøm II. Haøm OCIAttrGet() 1>Muïc ñích : nhaän moät thuoäc tính cuûa moät handle 2>Cuù phaùp : sword OCIAttrGet ( CONST dvoid *trgthndlp, ub4 trghndltyp, dvoid *attributep, ub4 *sizep, ub4 attrtype, OCIError *errhp ); 3>Caùc thamsoá trgthndlp(IN) : laø con troû chæ tôùi moät handle type trghndltyp(IN): laø handle type attripbutep(OUT) : con troû chæ tôùi vuøng chöùa giaù trò thuoäc tính . sizep(IN) : kích thöôùc cuûa vuøng chöùa giaù trò thuoäc tính . Caùc tham soá khoâng bieát kích thöôùc thì chuùng coù giaù trò NULL . Ñoái vôùi caùc tham soá text* , moät con troû chæ tôùi ub4 ñeå nhaän chieàu daøi cuûa chuoãi . attrtype(OUT) : kieåu cuûa thuoäc tính nhaän ñöôïc . errhp(IN/OUT) : moät loãi handle coù theå ñöôïc ñöa ñeán haøm OCIErrorGet() ñeå döï ñoaùn thoâng tin veà loãi ñoù . III. Haøm OCIAttrSet() 1>Muïc ñích :set moät thuoäc tính cuûa moät handle hoaëc moät descriptor 2>Cuù phaùp : sword OCIAttrSet ( dvoid *trgthndlp, ub4 trghndltyp, dvoid *attributep, ub4 size, ub4 attrtype, OCIError *errhp ); 3>Caùc tham soá : trgthndlp (IN/OUT) : con troû chæ tôùi moät handle maø coù thuoäc tính ñöôïc söûa chöõa trghndltyp (IN/OUT):kieåu handle attributep (IN) : con troû chæ tôùi chæ tôùi giaù trò thuoäc tính . Giaù trò naøy ñöôïc copy vao handle ñích . Neáu giaù trò naøy laø moät con troû thì chæ coù con troû ñöôïc copy chöù khoâng phaûi giaù trò cuûa noù. size (IN) : kích thöôùc cuûa moät giaù trò thuoäc tính , haàu heát caùc thuoäc tính maø kích thöôùc cuûa chuùng ñöôïc gaùn baèng 0 vì thö vieän OCI ñaõ bieát kích thöôùc cuûa chuùng . Ñoái vôùi caùc thuoäc tính kieåu text* thì ub4 phaûi ñöôïc ñöa vaøo chieâu daøi cuûa chuoãi. attrtype (IN) : kieåu cuûa thuoäc tính ñöôïc set . errhp (IN/OUT) : moät loãi handle coù theå ñöôïc ñöa ñeán haøm OCIErrorGet() ñeå döï ñoaùn thoâng tin veà loãi ñoù . Ví duï Sau ñaây laø moät ví duï giaûi thích caùch söû duïng haøm OCIAttrSet() vaøi laàn ñeå baét ñaàu moät öùng duïng . int main() { OCIEnv *envhp; OCIServer *srvhp; OCIError *errhp; OCISvcCtx *svchp; OCIStmt *stmthp; OCISession *usrhp; OCIInitialize((ub4) OCI_THREADED | OCI_OBJECT, (dvoid *)0, (dvoid * (*)()) 0,(dvoid * (*)()) 0, (void (*)()) 0 ); OCIHandleAlloc( (dvoid *) NULL, (dvoid **) &envhp, (ub4) CI_HTYPE_ENV, 0, (dvoid **) &tmp); OCIEnvInit( &envhp, (ub4) OCI_DEFAULT, 0, (dvoid **) &tmp ); OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &errhp, (ub4) OCI_HTYPE_ERROR, 0, (dvoid **) &tmp); OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &srvhp, (ub4) OCI_HTYPE_SERVER, 0, (dvoid **) &tmp); OCIServerAttach( srvhp, errhp, (text *) 0, (sb4) 0, (ub4) OCI_DEFAULT); OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &svchp, (ub4) OCI_HTYPE_SVCCTX, , (dvoid **) &tmp); /* set attribute server context in the service context */ OCIAttrSet( (dvoid *) svchp, (ub4) OCI_HTYPE_SVCCTX, (dvoid *) srvhp, (ub4) 0, (ub4) OCI_ATTR_SERVER, (OCIError *) errhp); /* allocate a user session handle */ OCIHandleAlloc((dvoid *)envhp, (dvoid **)&usrhp, (ub4) OCI_HTYPE_SESSION, (size_t) 0, (dvoid **) 0); OCIAttrSet((dvoid *)usrhp, (ub4)OCI_HTYPE_SESSION, (dvoid *)"sherry", (ub4)strlen("sherry"), OCI_ATTR_USERNAME, errhp); OCIAttrSet((dvoid *)usrhp, (ub4)OCI_HTYPE_SESSION, (dvoid *)"penfield", (ub4)strlen("penfield"), OCI_ATTR_PASSWORD, errhp); checkerr(errhp, OCISessionBegin (svchp, errhp, usrhp, OCI_CRED_RDBMS, OCI_DEFAULT)); OCIAttrSet((dvoid *)svchp, (ub4)OCI_HTYPE_SVCCTX, (dvoid *)usrhp, (ub4)0, OCI_ATTR_SESSION, errhp); } IV. Haøm OCIBindArrayOfStruct() 1>Muïc ñích :caøi ñaët caùc tham soá nhaûy cho moät maûng bind tónh 2>Cuù phaùp : sword OCIBindArrayOfStruct ( OCIBind *bindp, OCIError *errhp, ub4 pvskip, ub4 indskip, ub4 alskip, ub4 rcskip ); 3>Caùc tham soá : bindp (IN/OUT) :quaûn lyù moät caáu truùc bind. errhp (IN/OUT) :- moät loãi handle coù theå ñöôïc ñöa ñeán haøm OCIErrorGet() ñeå döï ñoaùn thoâng tin veà loãi ñoù . pvskip (IN) : tham soá nhaûy cho giaù trò döõ lieäu tieáp theo- indskip (IN) : tham soá nhaûy cho giaù trò indicator hoaëc caáu truùc tieáp theo. alskip (IN) : tham soá nhaûy cho giaù trò chieàu daøi thöïc tieáp theo. rcskip (IN) : tham soá nhaûy cho column-level tieáp theo traû veà maõ giaù trò. V. Haøm OCIBindByName() 1>Muïc ñích :taïo moät lieân keát giöõa moät bieán cuûa chöông trình vaø moät nôi chöùa trong moät phaùt bieåu SQL hoaëc khoái PL/SQL . 2>Cuù phaùp : sword OCIBindByName ( OCIStmt *stmtp, OCIBind **bindpp, OCIError *errhp, CONST text *placeholder, sb4 placeh_len, dvoid *valuep, sb4 value_sz, ub2 dty, dvoid *indp, ub2 *alenp, ub2 *rcodep, ub4 maxarr_len, ub4 *curelep, ub4 mode ); 3>Caùc tham soá : stmtp (IN/OUT) : phaùt bieåu ñieàu khieån ñeå xöû lyù phaùt bieåu SQL hoaëc PL/SQL. bindpp (IN/OUT) : moät ñòa chæ cuûa moät bind handle ñöôïc chæ ñònh bôûi lôøi goïi haøm naøy . Bind handle quaûn lyù taát caû thoâng tin veà bind cho töøng giaù trò ñaàu vaøo . Handle ñöôïc giaûi phoùng hoaøn toaøn khi statement handle bò deallocate . Giaù trò ñaàu vaøo phaûi laø pointer chæ NULL hoaëc bind handle coù hieäu löïc . errhp (IN/OUT) : moät loãi handle coù theå ñöôïc ñöa ñeán haøm OCIErrorGet() ñeå döï ñoaùn thoâng tin veà loãi ñoù . placeholder (IN) : moät nôi chöùa caùc thuoäc tính ñöôïc chæ ñònh baèng teân neáu haøm CIBindByName() ñöôïc goïi . placeh_len (IN) :chieàu daøi teân nôi chöùa ñöôïc ñònh roõ trong nôi chöùa. valuep (IN/OUT) : moät ñòa chæ cuûa giaù trò döõ lieäu hoaëc moät maûng caùc giaù trò döõ lieäu ñöôïc ñònh roõ trong tham soá dty.Moät maûng caùc giaù trò döõ lieäu coù theå ñöôïc ñònh roõ ñeå aùnh xaï vaøo moät baûng PL/SQL hoaëc ñeå cung caáp döõ lieäu cho caùc hoaït ñoäng SQL nhieàu doøng . Khi moät maûng caùc giaù trò bind ñöôïc cung caáp thì haøm naøy goïi moät maûng bind trong OCI term . Ñoái vôùi SQLT_NTY hoaëc SQLT_REF tham soá valuep bò phôùt lôø. Caùc con troû chæ ñeán caùc vuøng ñeäm OUT ñöôïc set trong tham soá pgvpp vaø ñöôïc khôûi taïo bôûi haøm OCIBindObject(). value_sz (IN) : kích thöôùc cuûa giaù trò döõ lieäu . Trong tröôøng hôïp maûng bind thì kích thöôùc lôùn nhaát coù theå cuûa moät phaàn töû laø kích thöôùc thaät ñöôïc ñònh roõ trong tham soá alenp . Ñoái vôùi descriptor, locator, hoaëc REF thì kích thöôùc cuûa chuùng khoâng ñöôïc bieát bôûi öùng duïng client söû duïng kích thöôùc cuûa caáu truùc do baïn aán ñònh , chaúng haïn sizeof (OCILobLocator *). dty (IN) : kieåu döõ lieäu cuûa giaù trò ñöôïc quy ñònh . Teân caùc kieåu döõ lieäu (SQLT_NTY) vaø REF (SQLT_REF) coù hieäu löïc neáu öùng duïng ñöôïc khôûi taïo trong cheá ñoä object . Ñoái vôùi caùc teân kieåu döõ lieäu hoaëc REF thì phaûi goïi theâm moät soá haøm vôùi bind handle ñöôïc caøi ñaët caùc thuoäc tính coù kieåu ñöôïc ñònh roõ . indp (IN/OUT) : con troû chæ ñeán moät bieán indicator hoaëc maûng . Ñoái vôùi taát caû kieåu döõ lieäu ngoaïi tröø SQLT_NTY thì tham soá naøy laø moät con troû troû ñeán sb2 hoaëc maûng sb2 . Ñoái vôùi SQLT_NTY thì pointer bò phôùt lôø vaø con thöïc troû ñeán caáu truùc indicator hoaëc maûng caùc caáu truùc indicator ñöôïc khôûi taïo sau khi goïi haøm OCIBindObject() . Tham soá naøy bò phôùt lôø ñoái vôùi caùc bind ñoäng (xem chöông 2) . alenp (IN/OUT) : con troû troû ñeán maûng caùc chieàu daøi thöïc cuûa maûng caùc phaàn töû . Moãi phaàn töû trong alen coù chieàu daøi döõ lieäu phuø hôïp vôùi phaàn töû trong maûng giaù trò bind tröôùc vaø sau khi thöïc thi . Tham soá naøy bò phôùt lôø ñoái vôùi caùc bind ñoäng rcodep (OUT) : con troû troû ñeán maûng column level traû veà maõ . tham soá naøy bò phôùt lôø ñoái vôùi caùc bind ñoäng . maxarr_len (IN) : soá phaàn töû lôùn nhaát cuûa kieåu dty trong moät Pl/SQL bind . Tham soá nay khoâng ñöôïc yeâu caàu ñoái caùc non-PL/SQL bind .Neáu maxarr_len khaùc 0 thì haøm OCIBindDynamic() hoaëc OCIBindArrayOfStruct() ñöôïc söû duïng ñeå caøi ñaët caùc thuoäc tính bind phuï. curelep(IN/OUT) : moät con troû troû ñeán soá caùc phaàn töû thöïc . Tham naøy khoâng ñöôïc yeâu caàu ñoái vôùi caùc PL/SQL bind. mode (IN) : caùc cheá ñoä coù hieäu löïc cho tham soá naøy laø : OCI_DEFAULT : ñaây laø cheá ñoä maëc ñònh . OCI_DATA_AT_EXEC :khi cheá ñoä naøy ñöôïc choïn thì tham soá value_sz xaùc ñònh kích thöôùc lôùn nhaát cuûa döø lieäu coù theå ñöôïc cung caáp vaøo thôøi gian chaïy. ÖÙng duïng phaûi saún saøng cung caáp cho thö vieän OCI thôøi gian chaïy caùc vuøng ñeäm döõ lieäu IN vaøo baát kyø thôøi ñieåm naøo vaø coù soá laàn baát kyø . Thôøi gian chaïy döõ lieäu ñöôïc cung caáp theo hai caùch : + Goïi laïi (callback) caùc haøm do user ñònh nghóa maø noù ñöôïc ghi sau khi goïi haøm OCIBindDynamic(). + Moät kyõ thuaät polling söû duïng caùc lôøi goïi ñöôïc cung caáp bôûi OCI . Cheá ñoä naøy giaû söû khoâng coù söï goïi laïi haøm ñöôïc ñònh nghóa naøo . 4>Lôøi bình Haøm naøy cuõng chæ ñònh tham soá bindpp troû ñeán bind handle . Neáu **bindpp khaùc NULL thì OCI giaû söû raèng con troû naøy troû ñeán handle coù hieäu löïc maø noù ñaõ ñöôïc chæ ñònh tröôùc ñoù thoâng qua lôøi goïi haøm OCIHandleAlloc() hoaëc OCIBindByName(). Döõ lieäu trong moät öùng duïng OCI coù theå ñöôïc gaén vôùi caùc nôi chöùa tónh hoaëc ñoäng . Binding laø tónh khi taát caû döõ lieäu bind IN(IN data bind) vaø caùc vuøng ñeäm bind OUT(OUT bind buffer) ñöôïc ñònh nghóa toát tröôùc khi thöïc thi . Binding laø ñoäng khi IN bind data vaø OUT bind buffer ñöôïc cung caáp bôûi öùng duïng maø thö vieän client yeâu caàu khi thöïc thi . Binding ñöôïc thieát laäp baèng vieäc thieát laäp tham mode = OCI_DATA_AT_EXEC (xem theâm chöông 7). Caû hai haøm OCIBindByName() vaø OCIBindByPos() nhaän moät tham soá laø bind handle maø noù hoaøn toaøn ñöôïc chæ ñònh bôûi bind call moät bind handle ñöôïc chæ ñònh cho moãi nôi chöùa öùng duïng laø binding . Ngoaøi ra caùc bind call ñöôïc yeâu caàu ñeå ñònh roõ caùc thuoäc tính caàn thieát khi binding caùc kieåu döõ lieäu naøo ñoù hoaëc xöû lyù döõ lieäu vaøo theo caùc caùch sau : Neáu caùc maûng caáu ñöôïc söû duïng thì haøm OCIBindArrayOfStruct() phaûi ñöôïc goïi ñeå thieát laäp caùc tham soá nhaûy caàn thieát . Neáu döõ lieäu ñöôïc cung caáp ñoäng vaøo thôøi gian chaïy vaø öùng duïng goïi laïi caùc haøm do user ñònh nghóa thì haøm OCIBindDynamic() ñöôïc goïi ñeå ghi laïi caùc callback Neáu teân kieåu döõ lieäu ñöôïc quy ñònh thì haøm OCIBindObject() ñöôïc goïi ñeå ñònh roõ caùc thoâng tin phuï caàn thieát . Neáu moät phaùt bieåu vôùi meänh ñeà RETURNING thì haøm OCIBindDynamic() phaûi ñöôïc goïi sau haøm naøy. VI. Haøm OCIBindByPos() 1>Muïc ñích : taïo moät lieân keát giöõa moät bieán cuûa chöông trình vaø nôi chöùa trong phaùt bieåu SQL hoaëc PL/SQL . 2>Cuù phaùp : sword OCIBindByPos ( OCIStmt *stmtp, OCIBind **bindpp, OCIError *errhp, ub4 position, dvoid *valuep, sb4 value_sz, ub2 dty, dvoid *indp, ub2 *alenp, ub2 *rcodep, ub4 maxarr_len, ub4 *curelep, ub4 mode ); 3>Caùc tham soá : stmtp (IN/OUT) : phaùt bieåu ñieàu khieån ñeå xöû lyù phaùt bieåu SQL hoaëc PL/SQL. bindpp (IN/OUT) : moät ñòa chæ cuûa moät bind handle ñöôïc chæ ñònh bôûi lôøi goïi haøm naøy . Bind handle quaûn lyù taát caû thoâng tin veà bind cho töøng giaù trò ñaàu vaøo . Handle ñöôïc giaûi phoùng hoaøn toaøn khi statement handle bò deallocate . Giaù trò ñaàu vaøo phaûi laø pointer chæ NULL hoaëc bind handle coù hieäu löïc . errhp (IN/OUT) : moät loãi handle coù theå ñöôïc ñöa ñeán haøm OCIErrorGet() ñeå döï ñoaùn thoâng tin veà loãi ñoù . position (IN) : nôi chöùa caùc thuoäc tính ñöôïc chæ ñònh bôûihaøm OCIBindByPos() . valuep (IN/OUT) : moät ñòa chæ cuûa giaù trò döõ lieäu hoaëc moät maûng caùc giaù trò döõ lieäu ñöôïc ñònh roõ trong tham soá dty.Moät maûng caùc giaù trò döõ lieäu coù theå ñöôïc ñònh roõ ñeå aùnh xaï vaøo moät baûng PL/SQL hoaëc ñeå cung caáp döõ lieäu cho caùc hoaït ñoäng SQL nhieàu doøng . Khi moät maûng caùc giaù trò bind ñöôïc cung caáp thì haøm naøy goïi moät maûng bind trong OCI term . Ñoái vôùi SQLT_NTY hoaëc SQLT_REF tham soá valuep bò phôùt lôø. Caùc con troû chæ ñeán caùc vuøng ñeäm OUT ñöôïc set trong tham soá pgvpp vaø ñöôïc khôûi taïo bôûi haøm OCIBindObject(). value_sz (IN) : kích thöôùc cuûa giaù trò döõ lieäu . Trong tröôøng hôïp maûng bind thì kích thöôùc lôùn nhaát coù theå cuûa moät phaàn töû laø kích thöôùc thaät ñöôïc ñònh roõ trong tham soá alenp . Ñoái vôùi descriptor, locator, hoaëc REF thì kích thöôùc cuûa chuùng khoâng ñöôïc bieát bôûi öùng duïng client söû duïng kích thöôùc cuûa caáu truùc do baïn aán ñònh , chaúng haïn sizeof (OCILobLocator *). dty (IN) : kieåu döõ lieäu cuûa giaù trò ñöôïc quy ñònh . Teân caùc kieåu döõ lieäu (SQLT_NTY) vaø REF (SQLT_REF) coù hieäu löïc neáu öùng duïng ñöôïc khôûi taïo trong cheá ñoä object . Ñoái vôùi caùc teân kieåu döõ lieäu hoaëc REF thì phaûi goïi theâm moät soá haøm vôùi bind handle ñöôïc caøi ñaët caùc thuoäc tính coù kieåu ñöôïc ñònh roõ . indp (IN/OUT) : con troû chæ ñeán moät bieán indicator hoaëc maûng . Ñoái vôùi taát caû kieåu döõ lieäu ngoaïi tröø SQLT_NTY thì tham soá naøy laø moät con troû troû ñeán sb2 hoaëc maûng sb2 . Ñoái vôùi SQLT_NTY thì pointer bò phôùt lôø vaø con thöïc troû ñeán caáu truùc indicator hoaëc maûng caùc caáu truùc indicator ñöôïc khôûi taïo sau khi goïi haøm OCIBindObject() . Tham soá naøy bò phôùt lôø ñoái vôùi caùc bind ñoäng (xem chöông 2) . alenp (IN/OUT) : con troû troû ñeán maûng caùc chieàu daøi thöïc cuûa maûng caùc phaàn töû . Moãi phaàn töû trong alen coù chieàu daøi döõ lieäu phuø hôïp vôùi phaàn töû trong maûng giaù trò bind tröôùc vaø sau khi thöïc thi . Tham soá naøy bò phôùt lôø ñoái vôùi caùc bind ñoäng rcodep (OUT) : con troû troû ñeán maûng column level traû veà maõ . tham soá naøy bò phôùt lôø ñoái vôùi caùc bind ñoäng . maxarr_len (IN) : soá phaàn töû lôùn nhaát cuûa kieåu dty trong moät Pl/SQL bind . Tham soá nay khoâng ñöôïc yeâu caàu ñoái caùc non-PL/SQL bind .Neáu maxarr_len khaùc 0 thì haøm OCIBindDynamic() hoaëc OCIBindArrayOfStruct() ñöôïc söû duïng ñeå caøi ñaët caùc thuoäc tính bind phuï. curelep(IN/OUT) : moät con troû troû ñeán soá caùc phaàn töû thöïc . Tham naøy khoâng ñöôïc yeâu caàu ñoái vôùi caùc PL/SQL bind. mode (IN) : caùc cheá ñoä coù hieäu löïc cho tham soá naøy laø : OCI_DEFAULT : ñaây laø cheá ñoä maëc ñònh . OCI_DATA_AT_EXEC :khi cheá ñoä naøy ñöôïc choïn thì tham soá value_sz xaùc ñònh kích thöôùc lôùn nhaát cuûa döø lieäu coù theå ñöôïc cung caáp vaøo thôøi gian chaïy. ÖÙng duïng phaûi saún saøng cung caáp cho thö vieän OCI thôøi gian chaïy caùc vuøng ñeäm döõ lieäu IN vaøo baát kyø thôøi ñieåm naøo vaø coù soá laàn baát kyø . Thôøi gian chaïy döõ lieäu ñöôïc cung caáp theo hai caùch : + Goïi laïi (callback) caùc haøm do user ñònh nghóa maø noù ñöôïc ghi sau khi goïi haøm OCIBindDynamic(). + Moät kyõ thuaät polling söû duïng caùc lôøi goïi ñöôïc cung caáp bôûi OCI . Cheá ñoä naøy giaû söû khoâng coù söï goïi laïi haøm ñöôïc ñònh nghóa naøo . 4>Lôøi bình Haøm naøy cuõng chæ ñònh tham soá bindpp troû ñeán bind handle . Neáu **bindpp khaùc NULL thì OCI giaû söû raèng con troû naøy troû ñeán handle coù hieäu löïc maø noù ñaõ ñöôïc chæ ñònh tröôùc ñoù thoâng qua lôøi goïi haøm OCIHandleAlloc() hoaëc OCIBindByName(). Döõ lieäu trong moät öùng duïng OCI coù theå ñöôïc gaén vôùi caùc nôi chöùa tónh hoaëc ñoäng . Binding laø tónh khi taát caû döõ lieäu bind IN(IN data bind) vaø caùc vuøng ñeäm bind OUT(OUT bind buffer) ñöôïc ñònh nghóa toát tröôùc khi thöïc thi . Binding laø ñoäng khi IN bind data vaø OUT bind buffer ñöôïc cung caáp bôûi öùng duïng maø thö vieän client yeâu caàu khi thöïc thi . Binding ñöôïc thieát laäp baèng vieäc thieát laäp tham mode = OCI_DATA_AT_EXEC (xem theâm chöông 7). Caû hai haøm OCIBindByName() vaø OCIBindByPos() nhaän moät tham soá laø bind handle maø noù hoaøn toaøn ñöôïc chæ ñònh bôûi bind call moät bind handle ñöôïc chæ ñònh cho moãi nôi chöùa öùng duïng laø binding . Ngoaøi ra caùc bind call ñöôïc yeâu caàu ñeå ñònh roõ caùc thuoäc tính caàn thieát khi binding caùc kieåu döõ lieäu naøo ñoù hoaëc xöû lyù döõ lieäu vaøo theo caùc caùch sau : Neáu caùc maûng caáu ñöôïc söû duïng thì haøm OCIBindArrayOfStruct() phaûi ñöôïc goïi ñeå thieát laäp caùc tham soá nhaûy caàn thieát . Neáu döõ lieäu ñöôïc cung caáp ñoäng vaøo thôøi gian chaïy vaø öùng duïng goïi laïi caùc haøm do user ñònh nghóa thì haøm OCIBindDynamic() ñöôïc goïi ñeå ghi laïi caùc callback Neáu teân kieåu döõ lieäu ñöôïc quy ñònh thì haøm OCIBindObject() ñöôïc goïi ñeå ñònh roõ caùc thoâng tin phuï caàn thieát . Neáu moät phaùt bieåu vôùi meänh ñeà RETURNING thì haøm OCIBindDynamic() phaûi ñöôïc goïi sau haøm naøy. VII. Haøm OCIBindDynamic() 1>Muïc ñích : ghi laïi caùc callback cuûa user ñoái vôùi vieäc chæ ñònh döõ lieäu ñoäng 2>Cuù phaùp : sword OCIBindDynamic ( OCIBind *bindp, OCIError *errhp, dvoid *ictxp, OCICallbackInBind (icbfp)(/*_ dvoid *ictxp, OCIBind *bindp, ub4 iter, ub4 index, dvoid **bufpp, ub4 *alenp, ub1 *piecep, dvoid **indpp */), dvoid *octxp, OCICallbackOutBind (ocbfp)(/*_ dvoid *octxp, OCIBind *bindp, ub4 iter, ub4 index, dvoid **bufpp, ub4 **alenpp, ub1 *piecep, dvoid **indpp, ub2 **rcodepp _*/) ); 3>Caùc tham soá : bindp (IN/OUT) : moät bind handle ñöôïc traû veà bôûi haøm OCIBindByName() hoaëc OCIBindByPos(). errhp (IN/OUT) : moät loãi handle coù theå ñöôïc ñöa ñeán haøm OCIErrorGet() ñeå döï ñoaùn thoâng tin veà loãi ñoù . ictxp (IN) :con troû ñöôïc yeâu caàu bôûi vieäc goïi laïi haøm icbfp. icbfp (IN) : haøm ñöôïc goïi laïi traû veà con troû troû tôùi giaù trò bind IN hoaëc moät boä phaän vaøo thôøi gian chaïy . ictxp (IN/OUT) : con troû ngöõ caûnh troû tôùi haøm callback . bindp (IN) : bind handle ñöôïc ñöa vaøo ñònh danh duy nhaát cuûa bieán bind iter (IN) : (= 0) döïa vaøo söï thöïc thi giaù trò laëp index (IN) : chæ soá maûng hieän taïi cho moät maûng bind trong PL/SQL. Ñoái vôùi SQL noù laø chæ soá doøng . Giaù trò cô sôû laø 0 vaø khoâng lôùn hôn tham soá curelep cuûa bind call. bufpp (OUT) :pointer troû tôùi buffer hoaëc storage. Ñoái vôùi caùc descriptor, *bufpp chöùa moät pointer troû tôùi descriptor. Ví duï neáu ñònh nghóa : OCILOBLocator *lobp; thì *bufpp troû tôùi lobp khoâng phaûi *lobp. Ñoái vôùi caùc REF, ñöa caùc ñòa chæ cuûa ref, chaúng haïn ñöa &my_ref cho *bufpp. alenp (OUT) : moät pointer troû tôùi storage ñeå OCI theâm ñaày kích thöôùc cuûa bind value/piece sau khi noù ñaõ ñöôïc ñoïc . Ñoái vôùi caùc descriptor thì ñöa kích thöôùc cuûa pointer vaøo descriptor chaúng haïn sizeof(OCILobLocator *). piecep (OUT):laø moät phaàn cuûa giaù trò bind , noù coù theå laø moät trong caùc giaù trò sau OCI_ONE_PIECE , OCI_FIRST_PIECE , OCI_NEXT_PIECE vaø OCI_LAST_PIECE. Ñoái vôùi caùc datatype maø khoâng hoã trôï caùc hoaït ñoäng piece khaùc(piecewise) thì ñöa OCI_ONE_PIECE vaøo hoaëc moät loãi ñöôïc taïo ra. indp (OUT) : chöùa giaù trò indicator . Noù laø moät pointer troû ñeán sb2 hoaëc moät caáu truùc indicator ñeå binding teân caùc kieåu döõ lieäu . octxp (IN) : pointer ngöõ caûnh caàn cho callback haøm ocbfp. ocbfp (IN) : callback haøm maø traû veà moät pointer troû ñeán giaù trò bind OUT hoaëc piece vaøo thôøi gian chaïy .Callback naøy nhaän caùc tham soá sau : octxp (IN/OUT) : con troû ngöõ caûnh cho callback haøm naøy. bindp (IN) : bind handle ñöôïc ñöa vaøo ñònh danh duy nhaát cuûa bieán bind naøy. iter (IN) : ( baét ñaàu töø 0) thöïc thi caùc giaù trò laëp. index (IN) : chæ soá PL/SQL cuûa maûng bind hieän taïi . Ñoái vôùi SQL, chæ soá naøy laø soá thöù töï haøng cuûa voøng laëp hieän taïïi the index is the row number in the current iteration . Baét ñaàu töø 0 vaø khoâng lôùn hôn tham soá curelep cuûa bind call. bufpp (OUT) : moät con troû troû tôùi vuøng ñeäm ñeå ghi bind value/piece. alenpp (IN/OUT) : moät con troû troû tôùi vuøng löu tröõ ñeå OCI ñieàn ñaày kích thöôùc cuûa bind value/piece sau khi noù ñöôïc ñoïc . piecep (IN/OUT) :traû veà moät phaàn trò töø callback (application) ñeán Oracle nhö sau : IN : giaù trò coù theå laø OCI_ONE_PIECE hoaëc OCI_NEXT_PIECE. OUT: tuøy theo giaù trò IN: Neáu giaù trò IN laø OCI_ONE_PIECE thì giaù trò OUT coù thheå laø OCI_ONE_PIECE hoaëc OCI_FIRST_PIECE Neáu giaù trò IN laø OCI_NEXT_PIECE thì giaù trò OUT coù theå laø OCI_NEXT_PIECE hoaëc OCI_LAST_PIECE indpp (OUT) : traû veà moät con troû chöùa giaù trò indicator hoaëc laø giaù trò sb2 hoaëc laø moät con troû troû tôùi moät caáu truùc indicator ñoái vôùi teân caùc kieåu döõ lieäu. rcodepp (OUT) : traû veà moät con troû chöùa maõ traû veà. 4>Lôøi bình : Lôøi goïi haøm naøy ñeå ghi laïi callback caùc haøm do user ñònh nghóa ñeå cung caáp hoaëc nhaän döõ lieäu neáu cheá ñoä OCI_DATA_AT_EXEC ñöôïc ñònh roõ trong lôùi goïi haøm OCIBindByName() or OCIBindByPos() tröôùc ñoù. Caùc pointer cuûa vieäc callback haûm phaûi traû veà OCI_CONTINUE neáu goïi thaønh coâng . Baát kyø maõ naøo khaùc OCI_CONTINUE thì client boû dôû quaù trình xöû lyù ngay töùc thì . Khi naïp ñòa chæ cuûa moät vuøng löu tröõ thì phaûi chaéc chaén raèng vuøng löu tröõ ñoù toàn taïi ngay caû sau khi öùng duïng traû veà töø callback , coù nghóa laø khoâng neân chæ ñònh quaù nhieàu vuøng löu tröõ treân stack . CHÖÔNG XI :CAÙC HAØM VAÄN CHUYEÅN (OCI Navigational Functions) Chöông naøy giôùi thieäu caùc haøm vaän chuyeån thoâng caùc object nhaän ñöôïc moät Oracle8 Server I. Giôùi thieäu Trong moâ hình object vaän chuyeån döõ lieäu ñöôïc moâ taû nhö laø moät graph cuûa object lieân keát vôùi nhau bôûi caùc tham chieáu . Caùc object trong moät graph ñöôïc tìm kieám theo caùc tham chieáu . OCI cung caáp moät giao tieáp navigation ñeán caùc object trong Oracle8 server . Moâi tröôøng object cuûa OCI ñöôïc khôûi taïo khi öùng duïng goïi haøm OCIInitialize() trong cheá ñoä OCI_OBJECT . II. Caùc object type vaø thôøi gian soáng Moät thöïc theå laø moät söï kieän xaûy ra cuûa moät kieåu ñöôïc ñònh nghóa trong moät CSDL Oracle . Phaàn naøy seõ giôùi thieäu moät thöïc theå ñöôïc hieän thöïc trong OCI nhö theá naøo . Trong OCI moät thöïc theå object ñöôïc phaân loaïi treân cô sôû kieåu , thôøi gian soáng vaø khaû naêng tham chieáu . 1)Moät persistent object laø moät thöïc theå cuûa moät object type . Moät persistent object truù nguï trong moät haøng cuûa baûng trong server vaø coù theå toàn taïi laâu thôøi gian hoaøn thaønh moät session(connection) . Persistent object coù theå ñöôïc ñònh nghóa bôûi caùc tham chieáu object chöùa ñònh danh (identifier) cuûa object . Moät persistent object thu ñöôïc bôûi pinning tham chieáu object cuûa noù . 2)Moät transient object laø moät thöïc theå cuûa moät object type . Moät transient object khoâng theå toàn taïi laâu hôn thôøi gian hoaøn thaønh moät session , noù ñöôïc söû duïng ñeå chöùa caùc keát quaû tính toaùn taïm thôøi . Transient object cuõng coù theå ñöôïc ñònh danh bôûi caùc tham chieáu chöùa caùc ñònh danh cuûa transient object . 3)Moät giaù trò laø moät thöïc theå cuûa moät kieåu do user ñònh nghóa (object type hoaëc collection type) hoaëc baát kyø kieåu ñöôïc xaây döïng trong Oracle . Khaùc vôùi caùc object , caùc giaù trò cuûa object ñöôïc nhaän ra bôûi caùc pointer boä nhôù chöù khoâng phaûi caùc tham chieáu . Moät giaù trò coù theå ñöùng moät mình (standalone) hoaëc ñöôïc theâm vaøo(embedded) . Moät gaù trò standalone thöôøng thu ñöôïc bôûi phaùt bieåu choïn . OCI cuõng cho pheùp moät chöông trình client choïn moät doøng cuûa baûng object vaøo moät giaù trò bôûi phaùt bieåu SQL . Vì vaäy moät object coù theå tham chieáu coù theå ñöôïc hieän thöïc nhö moät giaù trò (chöù khoâng ñöôïc ñònh danh bôûi moät tham chieáu ) . Moät giaù trò cuõng coù theå laø moät thuoäc tính out-of-life trong object (chaúng haïn VARCHAR ,raw) hoaëc moät phaàn töû out-of-line trong collection (chaúng haïn VARCHAR , raw ,object). Moät giaù trò embedded laø physically included trong moät containing instance. Moät giaù trò embedded coù theå laø moät thuoäc tính in-line trong moät object (chaúng haïn number ,nested object) hoaëc moät phaàn töû in-line trong moät collection . Taát caû giaù trò ñöôïc xaùc ñònh taïm thôøi bôûi OCI , chaúng haïn OCI khoâng hoå trôï töï ñoäng flushing moät giaù trò vaøo database ,coøn client thöïc thi hoaøn taát moät phaùt bieåu SQL ñeå löu giaù trò vaøo database . Caùc giaù trò embedded ñöôïc flush khi caùc containning instance ñöôïc flush . Hình sau cho thaáy caùc thöïc theå ñöôïc phaân loaïi theo kieåi cuûa chuùng vaø thôøi gian soáng : instance OBJECT VALUE Type …………… ……………………………………………………………………………………………………………………………. PERSISENT TRANSISENT LifetimelIFETIME Hình 14-1 Classification of Instances by Type and Lifetime Phaân bieät caùc thöïc theå khaùc nhau ñöôïc ñöa ra ôû baûng sau: Table 14-1 Distinctions Between Types of Objects Persistent Object Transient Object Value Type object type object type object type, built-in,collection Maximum Lifetime until object is deleted session session Referenceable yes yes no Embeddable no no yes III. Thuaät ngöõ Caùc thuaät ngöõ sau seõ ñöôïc söû duïng : 1)Term object ñöôïc söû duïng ñeå chæ moät persistent object, moät transient object, moät giaù trò standalone cuûa object type, hoaëc moät giaù trò embedded cuûa object type. 2)Term object coù theå tham chieáu chæ moät persistent object hoaëc moät transient object. 3)Term standalone object moät persistent object, moät transient object hoaëc moätgiaù trò standalone cuûa object type. 4)Term embedded object chæ moät giaù trò embedded cuûa object type. Moät object laø dirty neáu noù ñaõ ñöôïc taïo,hoaëc ñaùnh daáu caäp nhaät hoaëc xoùa. IV. Haøm navigation traû veà giaù trò Caùc haøm OCI navigation tieâu bieåu traû veà moät trong caùc giaù trò sau: Table 14-2 Common Navigational Function Return Values Return Value Meaning OCI_SUCCESS The operation succeeded OCI_ERROR The operation failed. The specific error can be retrieved by calling OCIErrorGet() on the error handle passed to the function. OCI_INVALID_HANDLE The environment or error handle passed to the function is NULL. V. Maõ loãi cuûa haøm navigation Baûng sau lieät keâ caùc maõ loãi beân ngoaøi cuûa Oracle coù theå ñöôïc traû veà bôûi moãi haøm navigation Table 14-3 OCI Navigational Function Error Codes Function Possible ORA Errors OCIObjectNew() 24350, 21560, 21705, 21710 OCIObjectPin() 24350, 21560, 21700, 21702 OCIObjectUnpin() 24350, 21560, 21710 OCIObjectPinCountReset() 24350, 21560, 21710 OCIObjectLock() 24350, 21560, 21701, 21708, 21710 OCIObjectMarkUpdate() 24350, 21560, 21700, 21701, 21710 OCIObjectUnmark() 24350, 21560, 21710 OCIObjectUnmarkByRef() 24350, 21560 OCIObjectFree() 24350, 21560, 21603, 21710 OCIObjectMarkDelete() 24350, 21560, 21700, 21701, 21702, 21710 OCIObjectMarkDeleteByRef() 24350, 21560 OCIObjectFlush() 24350, 21560, 21701, 21703, 21708, 21710 OCIObjectRefresh() 24350, 21560, 21709, 21710 OCIObjectCopy() 24350, 21560, 21705, 21710 OCIObjectGetTypeRef() 24350, 21560, 21710 OCIOjectGetObjectRef() 24350, 21560, 21710 OCIObjectGetInd() 24350, 21560, 21710 OCIObjectExists() 24350, 21560, 21710 OCIObjectIsLocked() 24350, 21560, 21710 OCIObjectIsDirty() 24350, 21560, 21710 OCIObjectPinTable() 24350, 21560, 21705 OCIObjectArrayPin() 24350, 21560 OCICacheFlush() 24350, 21560, 21705 OCICacheRefresh() 24350, 21560, 21705 OCICacheUnpin() 24350, 21560, 21705 OCICacheFree() 24350, 21560, 21705 OCICacheUnmark() 24350, 21560, 21705 OCIObjectSetAttr() 21560, 21600, 22305, 22279, 21601 OCIObjectGetAttr() 21560, 21600, 22305 YÙ nghóa cuûa loãi: ORA-21560 - name argument should not be NULL ORA-21600 - path expression too long ORA-21601 - attribute is not an instance of user-defined type ORA-21603 - cannot free a dirtied persistent object ORA-21700 - object does not exist or has been deleted ORA-21701 - invalid object ORA-21702 - object is not instantiated in the cache ORA-21703 - cannot flush an object that is not modified ORA-21704 - terminate cache or connection without flushing ORA-21705 - service context is invalid ORA-21708 - operations cannot be performed on a transient object ORA-21709 - operations can only be performed on a current object ORA-21710 - invalid pointer or value passed to the function ORA-22279 - cannot perform operation with LOB buffering enabled ORA-22305 - name argument is invalid ORA-24350 - this OCI call is not allowed from external subroutines VI. Toùm taét caùc haøm Table 14-4 OCI Navigational Functions Quick Reference Function Purpose FLUSH OR REFRESH OBJECT/CACHE OCICacheFlush() Flush modified persistent objects in cache to server OCIObjectFlush() Flush a modified persistent object to the server OCICacheRefresh() Refresh pinned persistent objects OCIObjectRefresh() Refresh a persistent object MARK OR UNMARK OBJECT/CACHE OCIObjectMarkDeleteByRef() Mark an object deleted given a ref OCIObjectMarkUpdate() Mark an object as updated/dirty OCIObjectMarkDelete() Mark an object deleted / delete a value instance OCICacheUnmark() Unmarks objects in the cache OCIObjectUnmark() Unmarks an object OCIObjectUnmarkByRef() Unmarks an object, given a ref to it GET OBJECT STATUS OCIObjectExists() Get the existent status of an instance OCIObjectIsDirty() Get the dirtied status of an instance OCIObjectIsLocked() Get the locked status of an instance PIN/UNPIN/FREE OCIObjectPin() Pin an object OCIObjectUnpin() Unpin an object OCIObjectPinCountReset() Unpin an object to zero pin count OCICacheUnpin() Unpin persistent objects in cache or connection OCIObjectArrayPin() Pin an array of references OCIObjectPinTable() Pin a table object with a given duration OCICacheFree() Free objects in the cache OCIObjectFree() Free a previously allocated object OTHER FUNCTIONS OCIObjectCopy() Copy one instance to another OCIObjectGetInd() Get null structure of an instance OCIObjectGetObjectRef() Return reference to a given object OCIObjectGetTypeRef() Get a reference to a TDO of an instance OCIObjectLock() Lock a persistent object OCIObjectNew() Create a new instance CHÖÔNG XII : AÙNH XAÏ KIEÅU DÖÕ LIEÄU OCI VAØ CAÙC HAØM THAO TAÙC I.Giôùi thieäu Chöông naøy giôùi thieäu caùc haøm aùnh xaï datatype OCI vaø caùc haøm thao taùc. Xem theâm chöông 9 II.Caùc haøm aùnh xaï datatype vaø caùc haøm thao taùc Caùc haøm aùnh xaï vaø caùc haøm thao taùc traû veà moät trong caùc giaù trò sau : Table 15-1 Common Navigational Function Return Values Return Value Meaning OCI_SUCCESS The operation succeeded OCI_ERROR The operation failed. The specific error can be retrieved by calling OCIErrorGet() on the error handle passed to the function. OCI_INVALID_HANDLE The environment or error handle passed to the function is NULL. Moät soá haøm traû veà caùc giaù trò khaùc trong baûng 15-1 . Khi söû duïng nhöõng haøm naøy phaûi coù moät nôi chöùa ñeå traû veà moät giaù trò tröïc tieáp töø lôøi goïi haøm hôn laø thoâng qua moät tham soá OUT . OCICollMax() OCIRawPtr() OCIRawSize() OCIRefHexSize() OCIRefIsEqual() OCIRefIsNull() OCIStringPtr() OCIStringSize() III.Giôùi thieäu caùc haøm Table 15-2 OCI Datatype Mapping and Manipulation Functions Quick Reference Function Purpose COLLECTION ITERATOR FUNCTIONS OCICollAppend() Collection append element OCICollAssignElem() Collection assign element OCICollAssign() Assign collection OCICollSize() get current size of collection (in number of elements) OCICollTrim() trim elements from the collection OCICollGetElem() get pointer to an element OCICollMax() return maximum number of elements in collection OCIIterCreate() Create ITerator to scan the varray elements OCIIterGetCurrent() get CURrent collection element OCIIterDelete() Delete ITerator OCIIterInit() Initialize ITerator to scan the given collection OCIIterNext() get NeXT collection element OCIIterPrev() get PReVious collection element, DATE FUNCTIONS OCIDateToText() convert date TO String OCIDateAddDays() ADd or subtract Days OCIDateAddMonths() ADd or subtract Months OCIDateDaysBetween() get number of days BeTWeen two dates OCIDateCheck() CHecK if the given date is valid OCIDateCompare() CoMPare dates OCIDateLastDay() get date of LaST day of month OCIDateNextDay() get date of Next DaY OCIDateFromText () convert String TO Date OCIDateSysDate() get current SYStem date and time OCIDateZoneToZone() convert date from one time Zone TO another Zone OCIDateAssign() assign date OCIDateGetDate() get the date portion of a date OCIDateGetTime() get the time portion of a date OCIDateSetDate() set the date portion of a date OCIDateSetTime() set the time portion of a date NUMBER FUNCTIONS OCINumberToInt() convert number TO Integer OCINumberToReal() convert number TO Real OCINumberToText() convert number TO String OCINumberAbs() ABSolute value OCINumberArcCos() Arc COSine OCINumberAdd() ADD numbers OCINumberAssign() ASsiGn number OCINumberArcSin () Arc SINe OCINumberArcTan() Arc TANgent OCINumberArcTan2() Arc TaNgent 2 OCINumberExp() arbitrary Base EXponentiation OCINumberCeil() CEiling of number OCINumberCmp() CoMPare numbers OCINumberCos() COSine OCINumberHypCos() CoSine Hyperbolic OCINumberDiv() DIVide numbers OCINumberPower() EXPonentiation to base e OCINumberFloor() FLooR of number OCINumberFromInt() convert Integer TO Number OCINumberIsZero() comparison with ZERo OCINumberLn() Logarithm Natural OCINumberLog () LOGarithm to arbitrary base OCINumberMod() MODulo division OCINumberMul() MULtiply numbers OCINumberNeg() NEGate number OCINumberIntPower() take an arbitrary base to an arbitrary integer PoWeR OCINumberFromReal() convert Real TO Number OCINumberRound() ROUnd Oracle number to a specified decimal place OCINumberSetZero() INItialize number to zero OCINumberFromText() convert String TO Number OCINumberSign() obtains SiGN of an Oracle number OCINumberSin() SINe OCINumberHypSin() SiNe Hyperbolic OCINumberSqrt() SQuare Root of number OCINumberSub() SUBtract numbers OCINumberTan() tANgent OCINumberHypTan() TaNgent Hyperbolic OCINumberTrunc() TRUncate an Oracle number at a specified decimal place REF FUNCTIONS OCIRefToHex() convert REF to Hexadecimal string OCIRefAssign() ASsiGn one REF to another OCIRefClear() CLeaR or nullify a REF OCIRefIsEqual() compare two REFs for EQUality OCIRefFromHex() convert Hexadecimal string to REF OCIRefHexSize() return size of hexadecimal representation OCIRefIsNull() test if a REF is NULl TABLE FUNCTIONS OCITableDelete() DELete element OCITableExists() Test whether element EXIsts OCITableFirst() return FirST index of table OCITableLast() return LaST index of table OCITableNext() return NeXT available index of table OCITablePrev() return PReVious available index of table OCITableSize() return current size of table STRING FUNCTIONS OCIStringAssign() Assign String to String OCIStringAllocSize() get Allocated SiZe of string memory in bytes OCIStringAssignText() Assign Text string to String OCIStringPtr() Get String Pointer OCIStringSize() Get String siZe OCIStringResize() ReSiZe string memory RAW FUNCTIONS OCIRawAssignBytes() Assign raw Bytes to Raw OCIRawAssignRaw() Assign Raw to Raw OCIRawAllocSize() Get Allocated SiZe of raw memory in bytes OCIRawPtr() Get Raw data Pointer OCIRawSize() Get Raw siZe OCIRawResize() ReSiZe memory of variable-length raw PHAÀN III : XAÂY DÖÏNG GIAO DIEÄN LAÄP TRÌNH OCI A-Toùm taét lyù thuyeát Treân cô sôû lyù thuyeát ñaõ trình baøy , vieäc xaây döïng caùc haøm môùi cuõng bao goàm taát caû caùc haøm OCI maø thöïc hieän caùc coâng vieäc cuûa moät chöông trình OCI . Sau laø moái töông quan giöõa caùc haøm OCI chuaån vaø caùc haøm ñaõ xaây döïng ñöôïc caàn söû duïng ñeå xaây moät chöông trình OCI cô baûn : Böôùc OCI chuaån Giao dieän môùi 1 1>Duøng haøm OCIInitialize() ñeå khôûi taïo caùc process 2>Duøng haøm OCIEnvInit() ñeå taïo environment handle 3>Duøng haøm OCIHandleAlloc() ñeå chæ ñònh service handle 4>Duøng haøm OCIHandleAlloc() ñeå chæ ñònh error handle 5>Duøng haøm OCIHandleAlloc() ñeå chæ ñònh server handle 6>Duøng haøm OCIHandleAlloc() ñeå chæ ñònh authentication handle 8>Duøng haøm OCIAtach() ñeå lieân keát vôùi server 9>Duøng haøm OCIAttrSet() thieát laäp server handle trong service handle 10>Duøng haøm OCIAttrSet() ñeå thieát laäp caùc thuoäc tính cuûa authentication handle(username vaø password) 11>Duøng haøm OCIAttrSet() ñeå thieát laäp authentication handle trong the Service handle 12>Duøng haøm OCISessionBegin() logon 1>Duøng haøm sword connect(const text *uid, const text *pwd, const text *hoststring) *uid (IN) : username *pwd (IN): password *hoststring(IN) :teân server Neáu logon thaønh coâng haøm traû veà OCI_SUCCESS Caùc giaù trò khaùc , logon bò loãi vaø caùc loãi naøy ñöôïc thoâng baùo baèng caùch goïi haøm massageError(errhp /* error hadle */) 2 13>Goïi haøm OCIHandleAlloc() ñeå chæ ñònh statement handle . Sau ñoù 14>Goïi haøm OCIStmtPrepare() ñeå chuaån bò phaùt bieåu 2>Goïi haøm sword prepare(text *sql) *sql (IN): leänh SQL Neáu prepare thaønh coâng haøm traû veà OCI_SUCCESS . Caùc giaù trò khaùc bò loãi 3 Neáu Bind theo teân : 15-1>Goïi haøm OCIHandleAlloc() ñeå chæ ñònh bind handle . Sau ñoù 16>Goïi haøm OCIBindByName() Neáu Bind theo vò trí : 15-1>Goïi haøm OCIBindByPos() Neáu duøng maûng caáu truùc : 15-1>Goïi haøm OCIBindByPos() hoaëc OCIBindByName() . Sau ñoù 15-2>Goïi Haøm OCIBindArrayOfStruct() Neáu bind ñoäng : 15-1>Goïi haøm OCIBindByPos() hoaëc OCIBindByName() 15-2>Xaây döïng haøm icbfp 15-3>Xaây döïng haøm ocbfp 15-4>Goïi haøm OCIBindDynamic() Neáu bind theo teân : 3-1>Goïi haøm sword bndName(text *prgvar, void *namecol, ub2 type, sword size) *prgvar (IN):bieán trong chöông trình *namecol (IN):teân coät type(IN) :maõ kieåu döõ lieäu cuûa coät size (IN) :kích thöôùc kieåu döõ lieäu Ví duï : SELECT dname FROM dept WHERE deptno= :num AND loc= :city; Thì prgvar=":num" Namecol=deptno Neáu bind theo vò trí thì goïi haøm: 3-1>Sword bndPos(ub4 pos, ub2 type, sword size) pos (IN) :vò trí cuûa bieán ñöôïc bind Trong ví duï treân pos cuûa deptno baèng 1 Neáu duøng maûng caáu truùc : 3-1>Goïi haøm sword bndArrOfStr(ArrayBind , int ) ArrayBind(OUT) :kieåu caáu truùc ñöôïc ñònh nghóa trong file OverOCI.h Int (IN): soá löôïng bieán caàn bind Neáu bind ñoäng : 3-1>Goïi haøm sword bndDynamic(int numbnds) numbnds (OUT): soá bieán caàn bind *pData[ ][ ](OUT):nôi döõ lieäu traû veà (ñöôïc khai baùo trong file OverOCI.h) 4 Thöïc thi : 16>Goïi haøm OCIStmtExecute() Thöïc thi : 4>Goïi haøm sword execute(int iters) iters : tham soá ñieàu khieån (xem phaàn lyù thuyeát) 5 Moâ taû caùc phaàn töû trong select-list : Moâ taû caùc phaàn töû trong select-list : 6 17>Goïihaøm OCIStmtExecute() trong cheá ñoä OCI_DESCRIBE_ONLY 18>Goïi haøm OCIAttrGet() nhaän soá column 19>Goïi haøm OCIParamGet() thieát laäp vieäc nhaän caùc tham soá coät I 20>Goïi haøm OCIAttrGet() nhaän kieåu döõ lieäu 21> Goïi haøm OCIAttrGet() nhaän kích thöôùc döõ lieäu 22> Goïi haøm OCIAttrGet() nhaän teân coät vaø chieàu daøi cuûa teân coät 5-1>Goïi haøm sword describe( ArrayDes arrDescribe[], int *numcols) arrDescribe(OUT) :xem ñònh nghóa trong file OverOCI.h *numcols :soá coät trong phaùt bieåu Neáu duøng haøm 5-2>Sword desAndDef(void *arrData[], ArrayDes arrDescribe[], int *numcols,sb2 indp[]) *arrData(OUT) :chöùa döõ lieäu traû veà trong caùc bieán ñaõ döôïc define trong chính haøm naøy (neáu duøng haøm naøy khoâng caàn goïi haøm define ) 7 Define Neáu Define theo vò trí : 23-1>Goïi haøm OCIDefineByPos() Neáu duøng maûng caáu truùc : 23-1>Goïi haøm OCIDefineByPos(). Sau ñoù 13-2>Goïi Haøm OCIDefineArrayOfStruct() Neáu Define ñoäng : 23-1>Goïi haøm OCIDefineByPos() hoaëc OCIDefineObject() 23-2>Xaây döïng haøm icbfp 23-3>Xaây döïng haøm ocbfp 23-4>Goïi haøm OCIDefineDynamic() 6-1>Goïi haøm sword definePos(sb4 size, ub2 type, void *data, int pos) size(IN):kích thöôùc döõ lieäu type(IN) :maõ kieåu *data(OUT) :con troû chæ tôùi vuøng döõ lieäu ñöôïc traû veà pos (IN): vò trí cuûa bieán ñöôïc define 6-2>Hoaëc (neáu duøng haøm naøy thì khoâng caàn duøng haøm fetchData() döõ lieäu seõ ñöôïc nhaän tröïc tieáp vaøo caùc bieán) sword defineArrOfStr( ArrayDefine ArrDef[], int numcols) ArrDef[ ](OUT): Maûng caùc coät , moãi phaàn töû laø moät maûng chöùa döõ lieäu Numcols(IN) : soá coät trong phaùt bieåu 8 24>Goïi haøm OCIStmtFetch() ñeå nhaän döõ lieäu 7>Goïi haøm sword fetchData() Moãi laàn nhaän moät row 9 Commit(coù theå khoâng coù böôùc naøy cuõng ñöôïc 25>Goïi haøm OCITransCommit() 8>Goïi haøm transCommit(ub4 flags) 10 Disconnect 26>Goïi haøm OCIFreeHandle() ñeå giaûi phoùng context handle thì caùc handle khaùc töï ñoäng ñöôïc giaûi phoùng Löu yù : coù theå giaûi phoùng caùc handle moät caùch töôøng minh Sau ñoù goïi haøm 27>OCISessionEnd() 9>Goïi haøm disconnecd() Nhö vaäy ñeå vieát moät chöông trình duøng tröïc tieáp caùc haøm OCI chuaån thì phaûi caàn khoaûng 26 ñeán 33 lôøi goïi haøm . Vôùi giao dieän môùi thì caàn khoaûng 7 ñeán 11 lôøi goïi haøm . Treân ñaây laø taát caû caùc böôùc cho vieäc vieát moät chöông trình OCI . Tuy nhieân tuøy töøng öùng duïng maø coù theå khoâng coù ñaày ñuû caùc böôùc naøy .