OCI-常用函数说明-OCIDefineByPos资源

一、初始化OCI程序环境。OCI8使用OCIInitialize函数来初始化OCI。这是使用OCI8与数据库建立会话必须的一步；同时，必须是第一步。如果成功，则返回0。函数原型：swordOCIInitialize(ub4mode,CONSTdvoid*ctxp,CONSTdvoid*(*malocfp)(/*dvoid*ctxp,size_tsize_*/),CONSTdvoid*(*ralocfp)(/*_dvoid*ctxp,dvoid*memptr,size_tnewsize_*/),CONSTvoid(*mfreefp)(/*_dvoid*ctxp,dvoid*memptr_*/))参数说明：1．mode——详细说明OCI初始化(Initialize)模式(mode)。它的取值如下：OCI_DEFAULT——缺省模式；OCI_THREADED——多线程模式；在该模式下，各并发处理中不为用户所见的内在数据结构受各自线程的保护，而不受别的线程干扰；OCI_OBJECT——使用目标特性；OCI_SHARED——使用共享内存；OCI_EVENTS——Mode参数可以拥有多个值，以“|”符号分隔各取值项。2．*Ctxp——用户定义的内存回调程序；默认为03．*(*malocfp)——用户定义的内存分配程序；默认为04．*(*ralocfp)——重新分配内存程序；默认为0 *memptr是指向内存块的指针；5．*mfreefp——用户定义的内存释放程序；默认为0该函数使用举例如下：OCIInitialize((ub4)OCI_THREADED|OCI_OBJECT,(dvoid*)0,(dvoid*(*)(dvoid*,size_t))0,(dvoid*(*)(dvoid*,dvoid*,size_t))0,(void(*)(dvoid*,dvoid*))0)注意！OCIEnvCreate()可以代替OCIInitialize()和OCIEnvInit()二、初始化OCI环境句柄。在初始化OCI程序环境以后，使用OCIEnvInit来初始化OCI的环境句柄，该函数成功返回0。函数原型：swordOCIEnvInit(OCIEnv**envhpp,ub4mode,size_txtramemsz,dvoid**usrmempp)参数说明：1．**envhpp——指向环境句柄的指针；2．mode——指定初始化环境句柄的模式，其取值如下：OCI_DEFAULT——缺省模式；在缺省模式下，OCI库始终互斥各环境句柄；OCI_NO_MUTEX——非互斥模式；在该模式下，OCI库各环境句柄并不互斥，所有的掉用都使用同一个环境句柄，并且只能有一个环境句柄起作用。OCI_ENV_NO_UCB——禁止回滚模式；该模式用以禁止在环境句柄初始化过程中的动态CALL_BACK函数掉用； 3．Xtramemsz——指定在该环境句柄生存期内分配内存的数量；4．**usrmempp——指向Xtramemsz参数的指针；usermempp参数是函数返回值；该函数使用举例如下：应用例子：OCIEnvInit((OCIEnv**)envhp,(ub4)OCI_DEFAULT,(size_t)0,(dvoid**)0)三、分配各OCI句柄。一个OCI连接在建立前，还需要将所需要的句柄一一分配成功，在OCI8里，使用函数OCIHandleAlloc来分配各句柄，成功返回0。函数原型：swordOCIHandleAlloc(CONSTdvoid*parenth,dvoid**hndlpp,ub4type,size_txtramem_sz,dvoid**usrmempp)参数说明：*parenth——已初始化后的环境句柄；**hndlpp——函数执行成功后，返回的一个OCI句柄；该返回值的具体含义由type参数来决定；type——参数hndlpp的返回值的类型；其常用取值如下：OCI_HTYPE_SVCCTX——返回一个服务类型的句柄；OCI_HTYPE_ERROR——返回一个错误类型的句柄；OCI_HTYPE_SESSION——返回一个会话类型的句柄；OCI_HTYPE_SERVER——返回一个服务器类型的句柄；OCI_HTYPE_STMT——返回一个陈述类型的句柄；其中，陈述类型的句柄是在创建与数据库会话成功后，将要对数据库进行操作时分配的，其余类型的句柄是在环境句柄初始化后分配的；xtramem_sz——指定在该句柄生存期内分配内存的数量；**usrmempp——指向xtramem_sz参数的指针，由函数返回；该函数使用举例如下：OCIHandleAlloc((dvoid*)*envhp,(dvoid**)errhp,(ub4)OCI_HTYPE_ERROR,(size_t)0,(dvoid**)0)四、为OCI操作数据源创建存储路径（以给定的方式设置服务器连接指针的参数）。分配各OCI句柄后，还需要做的工作是为OCI操作数据源创建存储路径，并将各项参数设置到相应的句柄中，这项工作由函数OCIServerAttach和OCIAttrSet来实现。成功，返回0。函数原型：swordOCIServerAttach(OCIServer*srvhp,OCIError*errhp,CONSTtext*dblink,sb4dblink_len,ub4mode)参数说明：*srvhp——已分配成功的服务器句柄；*errhp——已分配成功的错误类型句柄；若该函数执行出错，则该参数承载出错的原因；*dblink——登陆数据库的实例名；dblink_len——参数*dblink字符串的长度；mode——指定不同操作的模式。现在只有一种模式可选：OCI_DEFAULT。该函数使用举例如下：OCIServerAttach(srvhp,errhp, (text*)cstring,(sb4)strlen((char*)cstring),(ub4)OCI_DEFAULT))函数原型：swordOCIAttrSet(CONSTdvoid*trgthndlp,ub4trghndltyp,dvoid*attributep,ub4*sizep,ub4attrtype,OCIError*errhp)参数说明：*trgthndlp——需要设置的句柄，该句柄在这之前已分配成功；该参数由trghndltyp参数决定；trghndltyp——参数trgthndlp的类型，其取值参见OCIHandleAlloc函数说明中的type参数说明；*attributep——设置参数trgthndlp的值；*sizep——attributep参数指向的字符串长度；attrtype——参数attributep的类型；其取值如下：OCI_ATTR_SERVER——服务器类型；OCI_ATTR_USERNAME——用户名类型OCI_ATTR_PASSWORD——用户密码类型OCI_ATTR_SESSION——会话类型；*errhp——已分配成功的错误类型句柄；若该函数执行出错，则该参数承载出错的原因；该函数使用举例如下：OCIAttrSet((dvoid*)svchp,(ub4)OCI_HTYPE_SVCCTX,(dvoid*)srvhp,(ub4)0,(ub4)OCI_ATTR_SERVER,errhp))（注：此时该函数的意思是将服务器句柄设置到服务句柄中，其类型为服务器类型）说明：在登陆数据库前以给定的方式设置服务器连接指针的参数时，attrtype参数的所有类型都需要设置到服务句柄中。设置的步骤为：先将服务器句柄设置到服务句柄中，然后将用户名、密码设置到会话句柄中，在调用OCISessionBegin函数成功后，再将会话句柄设置到服务句柄中。五、创建并开始与数据库的会话创建和开始与数据库的会话使用函数OCISessionBegin来实现，其目的是建立与数据库的会话连接；函数成功，返回0。函数原型：swordOCISessionBegin(OCISvcCtx*svchp,OCIError*errhp,OCISession*authp,ub4credt, ub4mode))参数说明：*svchp——已分配并设置成功的服务句柄；*errhp——已分配成功的错误类型句柄；若该函数执行出错，则该参数承载出错的原因；*authp——已分配并设置了用户名、密码的会话句柄；credt——建立用户会话的类型；其取值如下：OCI_CRED_RDBMS——需要使用用户名和密码来建立会话；OCI_CRED_EXT——不需要使用用户名和密码来建立会话；mode——操作的模式；其取值如下：OCI_DEFAULT——缺省模式；在该模式下只支持一个会话句柄；OCI_MIGRATE——移动会话模式；在该模式下，新的会话连接会以不同的会话句柄返回；使用该模式创建新的会话时，必须已存在一个不可移动会话模式的会话连接。也就是说，一个移动会话模式的会话连接必须有一个不可移动模式的连接作为父连接；OCI_SYSDBA——在该模式下，会鉴别用户是否以SYSDBA形式对数据库进行访问；OCI_SYSOPER——在该模式下，会鉴别用户是否以SYSOPER形式对数据库进行访问；OCI_PRELIM_AUTH——这种模式和OCI_SYSDBA、OCI_SYSOPER一起使用，作为某些访问任务的鉴别；该函数使用举例如下：OCISessionBegin(svchp,errhp,authp,OCI_CRED_RDBMS,OCI_DEFAULT)六、取得errhp承载的错误原因。若某函数执行出错，则可以使用函数OCIErrorGet来取得错误原因，从而能得到某些提示。函数原型：swordOCIErrorGet(dvoid*hndlp,ub4recordno,text*sqlstate,sb4*errcodep,text*bufp,ub4bufsiz,ub4type)参数说明：*hndlp——错误类型句柄errhp；recordno——错误查找的原始位置，从1开始，其缺省值为1；*sqlstate——OCI8不支持，缺省值为NULL；*errcodep——ORACLE错误返回代码，由函数返回；初始值可以为（sb4）0；*bufp——错误信息提示，由函数以字符串形式返回；bufsiz——bufp参数原始字符串长度；type——句柄类型；其取值为OCI_HTYPE_ERR或着为OCI_HTYPE_ENV；缺省值为OCI_HTYPE_ERR；该函数使用举例如下：OCIErrorGet((dvoid*)errhp,(ub4)1,(text*)NULL,&errcode,(text*)msgbuf,(ub4)sizeof(msgbuf),(ub4)OCI_HTYPE_ERROR)七、准备执行用户定义的SQL或PL/SQL陈述语句。在执行SQL或PL/SQL语句前，需要对该语句执行分析、出错检查，并和陈述句柄棒定起来，使用函数OCIStmtPrepare来进行这一系列操作。该函数在执行陈述语句前必须使用；成功，返回0；函数原型：swordOCIStmtPrepare(OCIStmt*stmtp,OCIError*errhp,CONSTtext*stmt,ub4stmt_len,ub4language,ub4mode)参数说明：*stmtp——已分配成功的陈述句柄；*errhp——已分配成功的错误类型句柄；若该函数执行出错，则该参数承载出错的原因；*stmt——用户定义的需要执行的SQL或PL/SQL陈述语句；stmt_len——用户定义的需要执行的陈述语句的长度；该参数的值不能为0；language——语法模式；声明是本地语法，还是V7模式语法。其取值如下：OCI_V7_SYNTAX——ORACLE的V7分析语法；OCI_NTV_SYNTAX——语法依赖于服务器的版本；mode——模式；其缺省值为OCI_DEFAULT；该函数使用举例如下：OCIStmtPrepare(stmthp,errhp,sqlcommand,(ub4)strlen((char*)sqlcommand),(ub4)OCI_NTV_SYNTAX,(ub4)OCI_DEFAULT)八、定义输出变量。OCI执行陈述语句后，将所选择的变量值返回输出，此时需有用户定义的地址空间来容纳这些返回值。使用函数OCIDefineByPos通过在陈述语句中标志某变量在用户定义的变量集合中的位置来定义变量；若该函数执行成功，返回0。函数原型：swordOCIDefineByPos(OCIStmt*stmtp,OCIDefine**defnpp,OCIError*errhp,ub4position,dvoid*valuep,sb4value_sz,ub2dty,dvoid*indp,ub2*rlenp,ub2*rcodep,ub4mode)参数说明：*stmtp——用以进行查询的陈述语句句柄；该句柄必须是已经分配成功的句柄；**defnpp——用户定义的变量集合的指针；该参数指针从下标0开始，依次递增一个数组单元；*errhp——已分配成功的错误类型句柄；若该函数执行出错，则该参数承载出错的原因；position——需要定义的变量在定义句柄的列表中的位置，从1开始；例如：SELECTempno,ssn,mgrnoFROMemployees;则empno的position值为1，ssn的position的值为2，mgrno的position值为3；以此类推。*valuep——需要定义的变量的在执行成功后的存储地址；如果提取出来的数据有多项，则该参数可以使用数组；value_sz——valuep参数的指向的存储地址空间的长度；dty——需要定义的变量的数据类型；SQLT_STR表示该变量是个字符串变量；SQLT_INT则表示该变量是个整型变量；*indp——变量或数组指示器，默认为0；*rlenp——变量或数组长度指示器，默认为0；*rcodep——即将提取的变量的值指示器，默认为0；mode——变量提取模式。其取值为OCI_DEFAULT或OCI_DYNAMIC_FETCH；OCI_DYNAMIC_FETCH用于在提取资料过程中，需要动态资料的时候，此时必须用CIDefineDynamic函数建立一个回调函数用以提取数据；这种情况下，valuep和value_sz参数可以忽略；该函数使用举例如下：OCIDefineByPos(stmthp,&dfnhp[4],errhp,(ub4)5,(dvoid*)&No[0],(sb4)sizeof(No[0]),(ub2)SQLT_INT,(dvoid*)0,(ub2*)0,(ub2*)0,(ub4)OCI_DEFAULT）补充说明：如果输出变量是多行资料，则valuep参数应该为一个用户定义了大小的静态数组的初始地址，其大小为输出变量的行数与该变量自身大小的乘积。此时，在函数后面还需要使用另一个函数OCIDefineArrayOfStruct来定义该数组。函数OCIDefineArrayOfStruct说明如下：函数原形：swordOCIDefineArrayOfStruct(OCIDefine*defnp,OCIError*errhp,ub4pvskip,ub4indskip,ub4rlskip,ub4rcskip)参数说明：*defnp——从函数OCIDefineByPos返回的对应该变量的定义句柄，对应于OCIDefineByPos函数的第二项参数defnpp；*errhp——已分配成功的错误类型句柄；若该函数执行出错，则该参数承载出错的原因；pvskip——从本条记录中该变量的存储地址的到下条记录中该变量的存储地址之间的大小；也就是定义的一条记录的存储空间的大小；indskip——默认为0；rlskip——默认为0；rcskip——默认为0；该函数使用举例说明如下（对应于函数OCIDefineByPos的例子）：OCIDefineArrayOfStruct(dfnhp[4],errhp,sizeof(No[0]),0,0,0)九、定义输入变量OCI在执行陈述语句时，有时需要向该语句传递输入值，OCI8通过函数OCIBindByPos或OCIBindByName来实现该功能，OCIBindByPos将需要输入的变量与与其对应的参数值的位置绑定起来，从而实现向陈述语句中传递值的效果，而OCIBindByName则是通过绑定相应的变量名称来实现输入值的传递。函数原型：swordOCIBindByPos(OCIStmt*stmtp,OCIBind**bindpp,OCIError*errhp,ub4position,dvoid*valuep,sb4value_sz,ub2dty,dvoid*indp,ub2*alenp,ub2*rcodep,ub4maxarr_len,ub4*curelep,ub4mode)参数说明：*stmtp——用以进行查询的陈述语句句柄；该句柄必须是已经分配成功的句柄；**bindpp——用户定义的传入值集合的指针；该参数指针从下标0开始，依次递增一个数组单元；*errhp——已分配成功的错误类型句柄；若该函数执行出错，则该参数承载出错的原因；position——需要绑定的该变量在陈述语句的列表中的位置，从1开始，依次递增；*valuep——需要绑定的传入值的存储地址；value_sz——valuep参数的指向的存储地址空间的长度；dty——需要绑定的变量的数据类型；SQLT_STR表示该变量是个字符串变量；SQLT_INT则表示该变量是个整型变量；*indp——变量或数组指示器，默认为0；*alenp——变量或数组长度指示器，默认为0；*rcodep——即将提取的变量的值指示器，默认为0；maxarr_len——dyt参数的最大可能取值的数目，在非PL/SQL语句中该差数无效果；默认值为0；*curelep——对应与maxarr_len，表示dyt参数取值的实际数目；默认值为0；mode——变量提取模式。其取值为OCI_DEFAULT或OCI_DATA_AT_EXEC；当使用OCI_DATA_AT_EXEC时，value_sz表示在该陈述语句执行过程中可以使用的传入的该项值的最大存储长度，此时需要动态绑定该传入值；一般来说，mode的取值都为OCI_DEFAULT；该函数使用举例如下：OCIBindByPos(stmthp,&bndhp[3],errhp,(ub4)4,(dvoid*)register_number,(sb4)nLen,SQLT_STR,(dvoid*)0,(ub2*)0,(ub2*)0,(ub4)0,(ub4*)0,(ub4)OCI_DEFAULT)函数原型：swordOCIBindByName(OCIStmt*stmtp,OCIBind**bindpp,OCIError*errhp,CONSTtext*placeholder,sb4placeh_len,dvoid*valuep,sb4value_sz,ub2dty,dvoid*indp,ub2*alenp,ub2*rcodep,ub4maxarr_len,ub4*curelep,ub4mode)参数说明：*stmtp——用以进行查询的陈述语句句柄；该句柄必须是已经分配成功的句柄；**bindpp——用户定义的传入值集合的指针；该参数指针从下标0开始，依次递增一个数组单元；*errhp——已分配成功的错误类型句柄；若该函数执行出错，则该参数承载出错的原因；*placeholder——需要绑定的该变量在陈述语句中的占位符；placeh_len——palceholder参数的长度；*valuep——指向需要绑定的该变量的传入值的地址；value_sz——valuep参数存储的变量值的位组长度；dty——需要绑定的变量的数据类型；SQLT_STR表示该变量是个字符串变量；SQLT_INT则表示该变量是个整型变量；*indp——变量或数组指示器，默认为0；*alenp——变量或数组长度指示器，默认为0；*rcodep——即将提取的变量的值指示器，默认为0；maxarr_len——dyt参数的最大可能取值的数目，在非PL/SQL语句中该差数无效果；默认值为0；*curelep——对应与maxarr_len，表示dyt参数取值的实际数目；默认值为0；mode——变量提取模式。其取值为OCI_DEFAULT或OCI_DATA_AT_EXEC；当使用OCI_DATA_AT_EXEC时，value_sz表示在该陈述语句执行过程中可以使用的传入的该项值的最大存储长度，此时需要动态绑定该传入值；一般来说，mode的取值都为OCI_DEFAULT；该函数使用举例如下：OCIBindByName(stmthp,&bndhp[1],errhp,(text*)":field1",(sb4)strlen((char*)":phone_number"),(dvoid*)&to_field1,(sb4)sizeof(phone_number),SQLT_STR,(dvoid*)0,(ub2*)0,(ub2*)0,(ub4)0,(ub4*)0,(ub4)OCI_DEFAULT）补充说明：如果输入变量是多行资料，则valuep参数应该为一个用户定义了大小的静态数组的初始地址，其大小为输入变量的行数与该变量自身大小的乘积。此时，在函数后面还需要使用另一个函数OCIBindArrayOfStruct来定义该数组。函数OCIBindArrayOfStruct说明如下：函数原型：swordOCIBindArrayOfStruct(OCIBind*bindp,OCIError*errhp,ub4pvskip,ub4indskip,ub4alskip,ub4rcskip)参数说明：*bindp——从函数OCIBindByPos或OCIBindByName返回的对应该变量的绑定句柄，对应于函数OCIBindByPos或OCIBindByName的第二项参数bindpp；*errhp——已分配成功的错误类型句柄；若该函数执行出错，则该参数承载出错的原因；pvskip——从本条记录中该变量的存储地址的到下条记录中该变量的存储地址之间的大小；也就是定义的一条记录的存储空间的大小；indskip——默认为0；rlskip——默认为0；rcskip——默认为0；该函数使用举例如下：OCIBindArrayOfStruct(bndhp[N],errhp,sizeof(record_array[0]),indsk[N],rlsk[N],rcsk[N])十、执行陈述语句。在执行语句分析完成，并且变量定义或绑定完成后，便可以执行该陈述句柄，从而实现陈述语句中的SQL语句能完成的功能。使用函数OCIStmtExecute来执行该陈述句柄。执行成功，返回0；函数原型：swordOCIStmtExecute(OCISvcCtx*svchp,OCIStmt*stmtp,OCIError*errhp,ub4iters,ub4rowoff,CONSTOCISnapshot*snap_in,OCISnapshot*snap_out,ub4mode)参数说明：*svchp——已分配并设置成功的服务句柄；*stmtp——指向需要执行的陈述语句的句柄；*errhp——已分配成功的错误类型句柄；若该函数执行出错，则该参数承载出错的原因；iters——对于非选择语句来说，该函数执行次数等于iters减去rowoff的值；对于选择语句来说，如果iters不为0，则该函数在执行前必须有定义句柄（即需要定义位址空间来存储select出来的变量值），而函数会预先提取出多于iters条记录（如果可提取记录条数大于iters的话），将其中iters条正式提取出来；如果事先并不知道有多少条记录会被提取，则将iters的值置为0；在非选择语句中，若iters的值为0，则函数返回错误；rowoff——函数执行时，输入变量在绑定的变量数组的开始位置。用于多行记录的修改或插入、删除；比如，定义的绑定变量为array[100]，执行该函数时，iters的值为50，rowoff的值为10，则表示从array[10]开始提取传入值，而执行的次数则是50-10=40（次）；*snap_in——可选参数。默认值为0；*snap_out——可选参数。默认值为0；mode——执行模式；有四种执行模式：OCI_DEFAULT——缺省模式，在该模式下，总是隐式返回选择选择语句的有关描述信息；OCI_DESCRIBE_ONLY——在该模式下，陈述句柄并不被执行，但是它会返回可提取记录的条数；OCI_COMMIT_ON_SUCCESS——在该模式下，如若函数执行成功，则当前的处理马上会自动提交；OCI_EXACT_FETCH——该模式用于当前程序很明确的清楚有多少条记录会被提取出来；并且，使用该模式前必须要有定义句柄；该函数的使用举例如下：OCIStmtExecute(svchp,stmthp,errhp,(ub4)nCount,(ub4)0,(CONSTOCISnapshot*)0,(OCISnapshot*)0,(ub4)OCI_DEFAULT)另外，还可以使用函数OCIStmtFetch来提取固定数目的记录，其函数使用说明如下：函数原型：swordOCIStmtFetch(OCIStmt*stmtp,OCIError*errhp,ub4nrows,ub2orientation,ub4mode)参数说明：*stmtp——需要执行的陈述句柄；*errhp——已分配成功的错误类型句柄；若该函数执行出错，则该参数承载出错的原因；nrows——需要提取的记录的条数；orientation——该参数只有唯一一个缺省值：OCI_FETCH_NEXT；mode——默认为OCI_DEFAULT；该函数使用举例如下：swordOCIStmtFetch(stmtp,errhp,rows_number,OCI_FETCH_NEXT,OCI_DEFAULT)该函数成功执行，而无数据时，返回OCI_NO_DATA；十一、事务提交。在执行陈述句柄后，有的语句如insert、delete等需要提交当前事务，从而真正实现insert、delete等功能。OCI8使用函数OCITransCommit来实现这一功能。函数原型：swordOCITransCommit(OCISvcCtx*svchp,OCIError*errhp,ub4flags)参数说明：*svchp——已分配并设置成功的服务句柄；其值等于于OCIStmtExecute函数的srchp参数值。*errhp——已分配成功的错误类型句柄；若该函数执行出错，则该参数承载出错的原因；flags——提交标志。默认为0；该函数使用举例如下：OCITransCommit(svchp,errhp,(ub4)0)十二、事务回滚。在执行完陈述语句后，若需要取消当前执行的操作，则需要回滚当前事务。OCI8使用函数OCITransRollback来完成该功能。函数原型：swordOCITransRollback(dvoid*svchp,OCIError*errhp,ub4flags)参数说明：*svchp——需要回滚当前事务的服务句柄；其值等于于OCIStmtExecute函数的srchp参数值。*errhp——已分配成功的错误类型句柄；若该函数执行出错，则该参数承载出错的原因；flags——回滚标志。目前只有一个唯一的取值得：OCI_DEFAULT；该函数使用举例如下：OCITransRollback(svchp,errhp,OCI_DEFAULT)十三、断开与数据库的连接断开与数据库的连接需要进行下面一系列工作：结束当前会话、断开与数据库连接服务、释放分配的各个句柄。下面分别说明各项工作所使用的oci函数。结束当前会话：如果要断开与数据库的连接，则需要先结束当前会话，使用函数OCISessionEnd来完成该功能。执行成功，返回0函数原型：swordOCISessionEnd(OCISvcCtx*svchp,OCIError*errhp,OCISession*authp,ub4mode)参数说明：*svchp——需要断开的服务句柄；*errhp——已分配成功的错误类型句柄；若该函数执行出错，则该参数承载出错的原因；*authp——会话句柄；mode——会话结束模式。目前只有一种模式：OCI_DEFAULT；