KingbaseES客户端编程接口指南-DCI.pdf

KingbaseES 客户端编程接口指南-DCI 金仓数据库管理系统 KingbaseES 文档版本：V9（V009R001C001B0024） 发布日期：2023 年 10 月 12 日 北京人大金仓信息技术股份有限公司 目 目 录 录 第 1 章 前言 1 1.1 适用读者 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 相关文档 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.3 术语 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.4 手册约定 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 第 2 章 概述 3 2.1 OCI 和 DCI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.2 DCI 工作流程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.3 DCI 支持的数据类型 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 第 3 章 DCI 工程配置 7 3.1 Windows 平台工程搭建 (VS2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.2 Linux 平台工程搭建 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.3 服务的配置方法与参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.4 多主机地址配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 第 4 章 DCI 函数 15 4.1 DCIInitialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 4.2 DCIEnvCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 4.3 DCIEnvInit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 4.4 DCIHandleAlloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 4.5 DCIHandleFree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 4.6 DCIServerVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 4.7 DCIServerAttach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 4.8 DCIServerDetach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 4.9 DCISessionBegin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 4.10 DCISessionEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 4.11 DCILogon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 4.12 DCILogon2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 4.13 DCILogoff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 4.14 DCIStmtPrepare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 I 目 录 4.15 DCIStmtExecute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 4.16 DCIStmtFetch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 4.17 DCIStmtFetch2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 4.18 DCITransStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 4.19 DCITransCommit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 4.20 DCITransRollback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 4.21 DCIBindByName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 4.22 DCIBindByPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 4.23 DCIBindDynamic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 4.24 DCIStmtGetBindInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 4.25 DCIBindArrayOfStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 4.26 DCICloseSvcSocket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 4.27 DCIDefineByPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 4.28 DCIDefineArrayOfStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 4.29 DCIDescriptorAlloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 4.30 DCIDescriptorFree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 4.31 DCILobAssign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 4.32 DCILobAppend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 4.33 DCILobCopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 4.34 DCILobEnableBuffering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 4.35 DCILobDisableBuffering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 4.36 DCILobErase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 4.37 DCILobFlushBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 4.38 DCILobIsEqual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 4.39 DCILobLocatorIsInit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 4.40 DCILobCharSetForm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 4.41 DCILobCharSetId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 4.42 DCILobClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 4.43 DCILobCreateTemporary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 4.44 DCILobFreeTemporary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 4.45 DCILobIsTemporary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 4.46 DCILobIsOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 4.47 DCILobTrim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 4.48 DCILobGetLength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 4.49 DCILobOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 4.50 DCILobRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 4.51 DCILobRead2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 4.52 DCILobWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 4.53 DCINumberAdd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 4.54 DCINumberAssign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 4.55 DCINumberDiv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 4.56 DCINumberIsInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 II 目 录 4.57 DCINumberMod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 4.58 DCINumberMul . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 4.59 DCINumberAbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 4.60 DCINumberNeg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 4.61 DCINumberSub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 4.62 DCIDescribeAny . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 4.63 DCIParamGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 4.64 DCIAttrSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 4.65 DCIAttrGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 4.66 DCIObjectPin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 4.67 DCIObjectUnpin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 4.68 DCIObjectPinCountReset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 4.69 DCIObjectFree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 4.70 DCIBindObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 4.71 DCIDefineObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 4.72 DCIStringAssignText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 4.73 DCIStringPtr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 4.74 DCIDirPathPrepare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 4.75 DCIDirPathColArrayEntrySet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 4.76 DCIDirPathColArrayToStream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 4.77 DCIDirPathLoadStream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 4.78 DCIDirPathDataSave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 4.79 DCIDirPathColArrayReset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 4.80 DCIDirPathStreamReset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 4.81 DCIDirPathFinish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 4.82 DCIDirPathFlushRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 4.83 DCIErrorGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 4.84 DCIDateTimeConstruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 4.85 DCIDateTimeGetDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 4.86 DCIDateTimeGetTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 4.87 DCIIntervalGetDaySecond . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 4.88 DCIIntervalGetYearMonth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 4.89 DCIIntervalFromText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 4.90 DCIIntervalAssign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 4.91 DCIIntervalSetDaySecond . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 4.92 DCIIntervalSetYearMonth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 4.93 DCIIntervalAdd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 4.94 DCIIntervalToText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 4.95 DCINumberToText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 4.96 DCINumberFromText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 4.97 DCINumberToInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 4.98 DCINumberFromInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 III 目 录 4.99 DCINumberToReal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 4.100 DCINumberFromReal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 4.101 DCIDateGetDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 4.102 DCIDateGetTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 4.103 DCIDateSetDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 4.104 DCIDateSetTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 4.105 DCIDateSysDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 4.106 DCIDateAssign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 4.107 DCIDateTimeSysTimeStamp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 4.108 DCIDateTimeAssign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 4.109 DCIStmtGetPieceInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 4.110 DCIStmtSetPieceInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 4.111 DCIDurationBegin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 4.112 DCIDurationEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 4.113 DCIRowidToChar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 4.114 DCIDateTimeFromText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 4.115 DCIDateTimeToText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 4.116 DCIDateFromText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 4.117 DCIDateToText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 第 5 章 程序示例 132 5.1 登录和注销数据库 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 5.2 执行一条不返回结果的 SQL 语句 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 5.3 执行一条查询语句并获取结果 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 5.4 读取大字段数据 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 5.5 将数据写入大字段 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 5.6 DIRPATH 操作 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 5.7 批量插入 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 第 6 章 附录-DCI 错误码 163 版权声明 165 服务周期承诺 166 IV 第 1 章 前言 1 第 章 前言 本文档描述了 KingbaseES 兼容 OCI(Oracle Call Interface) 而成的 DCI 接口，并介绍了其相关用法。 前言部分包含以下主题： • 适用读者 • 相关文档 • 术语 • 手册约定 1.1 适用读者 KingbaseES DCI 指南面向所有使用 KingbaseES 数据库的用户，主要是数据库管理员和应用程序开发人员。 1.2 相关文档 有关 OCI 的更多信息，请参阅以下资源： Oracle Call Interface 1.3 术语 1.4 手册约定 本文档中可能出现“注意、提示、警告、另请参阅”等标志，它们所代表的含义如下： 1 第 1 章 前言 注意: 用于突出重要/关键信息、最佳实践等。 提示: 用于突出小窍门、捷径等。 警告: 用于传递设备或环境安全警示信息，若不避免，可能会导致设备损坏、数据丢失、设备性能降低或其 它不可预知的结果。 另请参阅: 用于突出参考、参阅等。 以下程序代码书写约定适用于本文档： 符号 说明 [] 表示包含一个或多个可选项。不需要输入中括号本身。 {} 表示包含两个以上（含两个）的候选，必须在其中选取一个。不需要输入花括号本身。 | 分割中括号或者花括号中的两个或两个以上选项。不需要输入“|”本身。 ... 表示其之前的元素可以被重复。 斜体 表示占位符或者需要提供特定值的变量。 大写 表示系统提供的元素，以便与用户定义的元素相互区分。除出现在方括号中的元素外，应当按 照顺序逐字输入。当然，部分元素在系统中是大小写不敏感的，因此用户可以根据系统说明以 小写形式输入。 小写 表示由用户提供的元素。 2 第 2 章 概述 2 第 章 概述 本手册为 KingbaseES 兼容 Oracle 的数据访问接口 Database Call Interface（以下简称 DCI）的使用说明文档。 • OCI 和 DCI • DCI 工作流程 • DCI 支持的数据类型 2.1 OCI 和 DCI OCI 是 Oracle 提供的一种应用程序编程接口（API），允许您创建使用函数调用来访问 Oracle 数据库、并控制 SQL 语句执行和数据访问的所有阶段的应用程序。 DCI 是 KingbaseES 提供的应用程序编程接口，该接口兼容 OCI 的功能，允许应用程序使用函数调用来访问 KingbaseES 数据库，并控制 SQL 语句执行和数据访问的所有阶段。 2.2 DCI 工作流程 DCI 工作流程如下图所示： 3 第 2 章 概述 图 2.2.1: DCI 工作流程 SQL 语句的执行流程如下图所示： 图 2.2.2: SQL 语句执行流程 4 第 2 章 概述 2.3 DCI 支持的数据类型 表 2.3.1: DCI 支持的数据类型 数据类型 类型说明 SQLT_CHR 字符串类型 SQLT_NUM 数值数据类型 SQLT_INT 整数类型（当指定长度为 1 时，对应 C 的 BYTE 类型；长度为 2 时， 对应 C 的 short 类型；长度为 4 时，对应 C 的 int 类型；长度为 8 时， 对应 C 的 int64 类型） SQLT_FLT 浮点数类型（当指定的长度为 4 时，对应 C 数据类型 float，当指定长 度为 8 时，对应 C 数据类型 double） SQLT_STR 变长字符串类型（末尾带有’0’ 结束符） SQLT_VNU 变长数值类型 SQLT_LNG 长整型类型 SQLT_VCS 变长字符串类型 SQLT_DAT 日期数据类型 SQLT_BFLOAT 单精度类型 SQLT_BDOUBLE 双精度类型 SQLT_BIN 二进制类型 SQLT_LBI 长二进制类型 SQLT_UIN 无符号整数类型 SQLT_LVC 超长的长整型（或字符串）类型 SQLT_LVB 超长的二进制类型 SQLT_AFC ANSI 定长字符串类型 SQLT_AVC ANSI 变长字符串类型 SQLT_CUR 游标类型 SQLT_CLOB 字符大对象类型 见续表 5 第 2 章 概述 表 2.3.1 – 续表 数据类型 类型说明 SQLT_BLOB 二进制大对象类型 SQLT_RSET 游标类型 SQLT_ODT 标准时间类型（兼容 Oracle 模式下的 DATE 类型） SQLT_DATE ANSI 日期类型 SQLT_TIME 时间类型 SQLT_TIME_TZ 带有区域的时间类型 SQLT_TIMESTAMP 时间戳类型 SQLT_TIMESTAMP_TZ 带有区域的时间戳类型 SQLT_TIMESTAMP_LTZ 带有本地区域的时间戳类型 SQLT_INTERVAL_YM YEAR-MONTH 的时间间隔类型 SQLT_INTERVAL_DS DAY-SECOND 的时间间隔类型 6 第 3 章 DCI 工程配置 3 第 章 DCI 工程配置 • Windows 平台工程搭建 (vs2008) • Linux 平台工程搭建 • 服务的配置方法与参数说明 • 多主机地址配置 3.1 Windows 平台工程搭建 (VS2008) a. 使用 VS 建立 DCI 工程，示例代码使用的是“程序示例-> 登陆和注销数据库”的用例。将 DCI 库包解压到需 求目录，本例的解压目录为 C:\dci_dll_dirpath 。 图 3.1.1: 应用程序界面展示 7 第 3 章 DCI 工程配置 b. 右键『解决方案资源管理器』中的 DCIApplication 项目，选择【属性】。在弹出的属性页中配置头文件路径: C/C++-> 常规-> 附加包含目录。 图 3.1.2: 配置头文件路径 c. 配置导入库: 链接器-> 输入-> 附加依赖项。 图 3.1.3: 配置导入库 d. 配置导入库路径: 链接器-> 常规-> 附加库目录。 8 第 3 章 DCI 工程配置 图 3.1.4: 配置导入库路径 e. 右键『解决方案资源管理器』中的 DCIApplication 项目，选择【生成】进行编译；选择菜单栏『调试』下的 【启动调试】或者按 F5 键，执行程序。 图 3.1.5: 应用程序执行结果 【提醒】 1. 在连接数据库前，请参照服务的配置方法与参数说明 ，配置服务文件 sys_service.conf。 9 第 3 章 DCI 工程配置 2. 运行程序需要配置 DLL 的路径： (1) 将 DLL 放置到应用程序生成目录； (2) 将动态库目录写入环境变量 PATH 中 (需要重启 visual studio 软件)。 3.2 Linux 平台工程搭建 1. 将 DCI 动态库 tar 包解压到需求目录，本例的解压目录为 /home/kingbase/DCITest ，示例代码使用的是“程 序示例-> 登陆和注销数据库”的用例。 图 3.2.1: 应用程序目录结构展示 2. 编译应用程序：本例使用的编译器是 GCC，对于不同的平台使用的编译器不同，根据需求和环境指定。-I 指定 引用的头文件路径；-L 指定引用的 DCI 动态库路径；-ldl 和-lm 是系统动态库，分别用于动态库加载和数学函 数调用。 图 3.2.2: 编译源文件 3. 设置环境变量：export KINGBASE_CONFDIR 指定 sys_service.conf 配置文件所在目录路径，配置方法请参 照服务的配置方法与参数说明 ；export LD_LIBRARY_PATH 指定 DCI 动态库所在目录路径，应用程序在运 行时加载。 图 3.2.3: 设置环境变量 4. 执行应用程序./test，得到执行结果。 10 第 3 章 DCI 工程配置 图 3.2.4: 应用程序执行结果 3.3 服务的配置方法与参数说明 DCI 通过服务名连接数据库。服务在文件 sys_service.conf 中配置。 在 DCI 中，可使用的参数和含义如下所示： • host 数据库服务器的地址，包括域名、主机名、主机的 IP 地址等，如果有多个 host 值可以使用“,”将它们分 隔开或使用”( )” 将他们括起来。 • port 端口号 • dbname 数据库名 • Print 是否打印语句信息（输出到标准输出，而非日志文件；取值 0 或者 1） • DCILog 指定日志信息文件的保存路径（文件可不存在，但是其父目录必须存在，并且有写权限）日志配置是 全局生效的，所以 DCI 只会根据找到的第一个有效的日志参数值为准。因此如果有多个数据源都有日志配置， 其实也只有第一个日志配置参数生效。 • DCILogLevel 指定日志级别，可取值为：LOG / DEBUG1 / DEBUG2 / DEBUG3 / DEBUG4 / DEBUG5 • UseDciDat 当 UseDciDat=0 时，对于数据库中的 timestamp 类型，返回的 DCI 类型为 SQLT_DAT，默认值为 0。 当 UseDciDat=1 时，对于数据库中的 timestamp(0)，返回的 DCI 类型为 SQLT_DAT；对于其他的 timestamp 类型返回的 DCI 类型为 SQLT_TIMESTAMP。 当 UseDciDat=2 时， 对 于 数 据 库 中 的 timestamp 类 型， 无 论 精 度 是 多 少， 返 回 的 DCI 类型为 SQLT_TIMESTAMP。 UseDciDat 取 0，1，2 以外的值时，接口按照默认值 0 进行处理。 • AutoCommit 是否采用自动提交事务方式，默认是 1，表示采用自动提交模式；如果指定为 0，表示采用手动提 交模式。 • BatchInsertSize_Ext 批量 DML 扩展优化 指定是否开启批量 INSERT，UPDATE，DELETE 扩展优化，默认值为 0 表示关闭。如果指定为 1，则会开启 批量 DML 扩展优化。该参数仅在 V8R6C4 及以上版本的 KingbaseES 数据库上支持。 • SSLMode SSL 加密连接的方式 11 第 3 章 DCI 工程配置 指定 SSL 加密连接的模式。可配置值如下所示： d(disable: 关闭，不关心安全，不想花费加密开销) a(allow: 允许，不关心安全性，但如果服务器支持，则会花费加密开销) p(prefer: 优先，不关心加密，但如果服务器支持，则花费加密开销) r(require: 要求，希望数据是加密的并接受加密开销，默认当前网络将确保始终连接到想要连接的服务器) vc(verify-ca: 验证 CA，希望数据是加密的并接受加密开销，确保连接到受信任的服务器) vf(verify-full: 全验证，希望数据是加密的并接受加密开销，确保连接到指定的受信任的服务器) • pqopt SSL 加密连接相关的从属配置 指定 SSL 加密连接相关的从属（证书路径）配置，Windows 平台上所有的子配置项需要放在大括号”{}” 中。 子配置项有如下几个： sslrootcert：可信的证书机构 sslcert：客户端证书 sslkey：客户端私钥 配置示例： Windows 平台： pqopt={sslrootcert=D:\sslconf\root.crt sslcert=D:\sslconf\kingbase8.crt sslkey=D:\sslconf\ kingbase8.key} Linux 平台： pqopt=sslrootcert=/home/sslconf/root.crt sslcert=/home/sslconf/kingbase8.crt sslkey=/home/ sslconf/kingbase8.key • Protocol 语句级自动回滚配置项 目前只能严格按照如下配置值进行配置，默认情况下不开启该配置： Protocol=7.4-0：不开启语句级自动回滚 Protocol=7.4-2：开启语句级自动回滚 该配置项需配合 AutoCommit 配置项使用，在 AutoCommit=0 时，可通过上述配置开启（取消）语句级 自动回滚，在 AutoCommit=1 时，该配置无效；当 AutoCommit=0 且不使用该配置项时，默认值等同于 Protocol=7.4-0。 • AutoCommitDDL 是否开启 DDL 语句自动提交事务，默认是 0，表示不采用 DDL 语句自动提交模式；如果指 定为 1，表示采用 DDL 语句自动提交模式。该配置只在 AutoCommit=0 时有效。 注意: • sys_service.conf 文件的书写格式如下： 12 第 3 章 DCI 工程配置 [servicename1] keyword=value ... [servicename2] ... 示例： [kingbase] host=192.168.0.1,198.168.0.2 dbname=SAMPLES port=54321 • 在 sys_service.conf 文件中服务名使用方括号’[]’ 识别, 如果出现多个相同的服务名 (不区分大小写)，第一个出现 的那个将被使用；如果一个服务中出现多个相同参数（host 除外），最后一个出现的那个将被使用；如果参数 是 host，则直接把其 host 值加入 host 列表中。 • sys_service.conf 文件每行不得超过 256 个字符，使用“#“来进行注释 • sys_service.conf 文件所在路径： DCI 接口提供两种配置方法，用来建立与 sys_service.conf 的关联： – 根据不同平台，将 config 文件夹中的 sys_service.conf 拷贝到指定的路径下： Windows XP 指定路径为：X:\Documents and Settings\All Users\Application Data\KingbaseES 目录。 Windows 7 指定路径为：X:\ProgramData\KingbaseES 目录。 Linux 指定路径为：/etc 目录。 注： 1. 路径中 KingbaseES 文件夹需要用户自己建立； 2. X 为系统盘符； 3. 在 Windows 平台，需注意 Application Data 与 ProgramData 为系统隐藏文件夹。 – 指定环境变量 在 Windows 和 Linux 平台，用户可以根据需要更改 sys_service.conf 文件的位置，但在连接数据库之前需 要通过设置环境变量 KINGBASE_CONFDIR 指定其所在目录的路径。 • keyword 格式说明：keyword 以及其后的 value 不区分大小写；keyword 之前以及’=’ 前后允许有空格，但 keyword 和 value 内部的空格不会被忽略；若想将 keyword 赋为空串，则’=’ 后的 value 保持空白即可（” 或”” 不 会作为空串而是作为 value 值处理）。 • 如果使用 DCI 接口的应用程序以“IP:PORT:DBNAME”的方式连接数据库，则 sys_service.conf 文件中服务 名为“Default”的配置将生效。 13 第 3 章 DCI 工程配置 • 如果使用 DCI 接口的应用程序以“IP:PORT:DBNAME”的方式连接数据库，但是无法通过默认路径或指定的 环境变量找到 sys_service.conf 配置文件时，应用程序将在 DCI 默认参数下启动，默认参数为： AutoCommit=0 AutoCommitDDL=1 BatchInsertSize_Ext=1 Protocol=7.4-2 注：该功能生效后，在 DCI 端会有两套默认值，即原有的默认值模式和类 Oracle 默认值模式，只有在当前配 置中描述的情况下，参数的默认值才会采用类 Oracle 的默认值模式。其他情况下为了与原有功能保持一致，所 以保持了原有的默认值。两套默认值的不同在于：原默认值中默认 AutoCommit=1，并且不配置 BatchInsertSize_Ext，即默认该配置为 0；类 Oracle 默认值则开启上述四个配置。 多主机地址配置 3.4 通过此配置方法，可以实现多主机地址连接，并区分主备机。 多主机配置示例（只连接主机，连接超时 5 秒，ACK 超时 3000 毫秒），以 Windows 平台配置为例： [Kingbase] host=192.168.0.1,192.168.0.2 dbname=test user=system port=54321 pqopt=application_name=kingbase target_session_attrs=read-write connect_timeout=5 tcp_user_timeout=3000 该示例中参数含义如下所示： • host：配置多个地址，使用逗号分隔，驱动处理时会按顺序连接，直到有一个成功并符合 target_session_attrs 条件并返回。 • pqopt：配置其它扩展参数，中间用空格分隔（Windows 平台上所有的子配置项需要放在大括号”{}” 中）。 其他扩展参数解释： – application_name：表明连接到数据库服务器的应用名称。 – target_session_attrs=read-write：表明只返回可读写的节点连接，即主机连接，如果不满足，会继续尝试 下一个地址。默认是 any，即主备都可以。 – connect_timeout=5：表示连接超时时间，单位是秒，最少 2 秒，默认为 10 秒。如果是多个地址，就是指 所有连接尝试的总时长。 – tcp_user_timeout=3000：表示 TCP 报文的等待 ACK 的最大等待时间，单位为毫秒，默认为 0，即没有 限制，以操作系统配置为准。 其它可配置参数可参见服务的配置方法与参数说明。 14 第 4 章 DCI 函数 4 第 章 DCI 函数 • DCIInitialize • DCIEnvCreate • DCIEnvInit • DCIHandleAlloc • DCIHandleFree • DCIServerVersion • DCIServerAttach • DCIServerDetach • DCISessionBegin • DCISessionEnd • DCILogon • DCILogon2 • DCILogoff • DCIStmtPrepare • DCIStmtExecute • DCIStmtFetch • DCIStmtFetch2 • DCITransStart • DCITransCommit • DCITransRollback • DCIBindByName • DCIBindByPos 15 第 4 章 DCI 函数 • DCIBindDynamic • DCIStmtGetBindInfo • DCIBindArrayOfStruct • DCICloseSvcSocket • DCIDefineByPos • DCIDefineArrayOfStruct • DCIDescriptorAlloc • DCIDescriptorFree • DCILobAssign • DCILobAppend • DCILobCopy • DCILobEnableBuffering • DCILobDisableBuffering • DCILobErase • DCILobFlushBuffer • DCILobIsEqual • DCILobLocatorIsInit • DCILobCharSetForm • DCILobCharSetId • DCILobClose • DCILobCreateTemporary • DCILobFreeTemporary • DCILobIsTemporary • DCILobIsOpen • DCILobTrim • DCILobGetLength • DCILobOpen • DCILobRead • DCILobWrite • DCINumberAdd • DCINumberAssign 16 第 4 章 DCI 函数 • DCINumberDiv • DCINumberIsInt • DCINumberMod • DCINumberMul • DCINumberAbs • DCINumberNeg • DCINumberSub • DCIDescribeAny • DCIParamGet • DCIAttrSet • DCIAttrGet • DCIObjectPin • DCIObjectUnpin • DCIObjectPinCountReset • DCIObjectFree • DCIBindObject • DCIDefineObject • DCIStringAssignText • DCIStringAssignText • DCIDirPathPrepare • DCIDirPathColArrayEntrySet • DCIDirPathColArrayToStream • DCIDirPathLoadStream • DCIDirPathDataSave • DCIDirPathColArrayReset • DCIDirPathStreamReset • DCIDirPathFinish • DCIDirPathFlushRow • DCIErrorGet • DCIDateTimeConstruct • DCIDateTimeGetDate 17 第 4 章 DCI 函数 • DCIDateTimeGetTime • DCIIntervalGetDaySecond • DCIIntervalGetYearMonth • DCIIntervalFromText • DCIIntervalAssign • DCIIntervalSetDaySecond • DCIIntervalSetYearMonth • DCIIntervalAdd • DCIIntervalToText • DCINumberToText • DCINumberFromText • DCINumberToInt • DCINumberFromInt • DCINumberToReal • DCINumberFromReal • DCIDateGetDate • DCIDateGetTime • DCIDateSetDate • DCIDateSetTime • DCIDateSysDate • DCIDateAssign • DCIDateTimeSysTimeStamp • DCIDateTimeAssign • DCIStmtGetPieceInfo • DCIStmtSetPieceInfo • DCIDurationBegin • DCIDurationEnd • DCIRowidToChar • DCIDateTimeFromText • DCIDateTimeToText • DCIDateFromText 18 第 4 章 DCI 函数 • DCIDateToText 4.1 DCIInitialize 函数原型： sword DCIInitialize(ub4 mode, dvoid *ctxp, dvoid *(*malocfp)(dvoid *ctxp, size_t size), dvoid *(*ralocfp)(dvoid *ctxp, dvoid *memptr, size_t newsize), void (*mfreefp)(dvoid *ctxp, dvoid *memptr) ) 功能描述： 初始化 DCI 全局环境，DCI 会在这个函数中初始化内部的全局变量和加载一些配置信息，这是使用 DCI 与数据 库建立连接必须的第一步。 参数说明： • mode(输入) 初始化模式。取值如下： – DCI_DEFAULT：缺省模式 – DCI_THREADED：多线程模式 • ctxp(输入/输出) 用户自定义的内存回调程序指针，目前不使用。 • malocfp(输入) 用户自定义的内存分配程序指针，目前不使用。 • ralocfp(输入) 用户自定义的重分配内存程序指针，目前不使用。 • memptr(输入/输出) 指向内存块的指针，目前不使用。 • mfreefp(输入) 用户自定义的内存释放程序指针，目前不使用。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 该函数在每个应用中只需调用一次。 19 第 4 章 DCI 函数 4.2 DCIEnvCreate 函数原型： sword DCIEnvCreate (DCIEnv **envp, ub4 mode, const void *ctxp, const void *(*malocfp)(void *ctxp, size_t size), const void *(*ralocfp)(void *ctxp, void *memptr, size_t newsize), const void (*mfreefp)(void *ctxp, void *memptr)) 功能描述： 分配并初始化 DCI 环境句柄, 此函数必须在 DCIInitialize 之后调用。 参数说明： • envp(输入) 输出一个生成的环境句柄指针，应用可以在环境句柄上分配其它类型的句柄。 • mode(输入) 初始化模式。取值如下： – DCI_DEFAULT：缺省模式 – DCI_THREADED：多线程模式 – DCI_OBJECT：指定此 mode 值向 DCI 库表明应用程序正在使用对象 • ctxp(输入/输出) 用户自定义的内存回调程序指针，目前不使用 (仅用于和 Oracle 保持兼容)。 • malocfp(输入) 用户自定义的内存分配程序指针，目前不使用 (仅用于和 Oracle 保持兼容)。 • ralocfp(输入) 用户自定义的重分配内存程序指针，目前不使用 (仅用于和 Oracle 保持兼容)。 • memptr(输入/输出) 指向内存块的指针，目前不使用 (仅用于和 Oracle 保持兼容)。 • mfreefp(输入) 用户自定义的内存释放程序指针，目前不使用 (仅用于和 Oracle 保持兼容)。 • xtramem_sz(输入) 指定在环境持续时间内要分配的用户内存量，目前不使用 (仅用于和 Oracle 保持兼容)。 20 第 4 章 DCI 函数 • usrmempp(输出) 返回指向用户内存的指针，大小为 xtramem_sz，目前不使用 (仅用于和 Oracle 保持兼容)。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 当调用该函数初始化一个环境句柄以后，必需调用 DCIHandleFree 来释放这个句柄。需要注意的是，当环境句 柄分配以后，只允许在上面分配一个上下文句柄，并只允许建立一个连接；但是在连接建立以后，允许分配多个语句 句柄。 4.3 DCIEnvInit 函数原型： sword DCIEnvInit(DCIEnv **envp, ub4 mode, size_t xtramem_sz, dvoid **usrmempp) 功能描述： 功能与 DCIEnvCreate 相同。分配并初始化 DCI 环境句柄, 此函数必须在 DCIInitialize 之后调用。 参数说明： • envp(输出) 输出一个生成的环境句柄指针，应用可以在环境句柄上分配其它类型的句柄。 • mode(输入) 初始化模式。取值如下： – DCI_DEFAULT：缺省模式 – DCI_THREADED：多线程模式 • xtramem_sz(输入) 用户自定义分配内存的大小，目前不使用。 • usrmempp（输出） 指向用户自定义分配内存的指针，目前不使用。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 21 第 4 章 DCI 函数 当调用该函数初始化一个环境句柄以后，必须调用 DCIHandleFree 来释放这个句柄。 4.4 DCIHandleAlloc 函数原型： sword DCIHandleAlloc(dvoid *parenth, dvoid **hndlpp, CONST ub4 type, CONST size_t xtramem_sz, dvoid **usrmempp) 功能描述： 分配并初始化各类应用句柄。 参数说明： • parenth(输入) 一个环境句柄的指针，从该句柄上可以分配其它类型的句柄。 • hndlpp(输出) 返回新分配的句柄指针。 • type(输入) 指定要从环境句柄上分配的句柄类型。可以分配的句柄类型有： – DCI_HTYPE_SERVER 分配一个 DCIServer 结构句柄 (连接句柄)，该句柄上存放建立的连接句柄。 – DCI_HTYPE_SESSION 分配一个 DCISession 结构句柄 (连接信息句柄)，该句柄上存放建立连接所用的登录信息，比如登录的口 令和密码。 – DCI_HTYPE_SVCCTX 分配一个 DCISvcCtx 结构句柄 (上下文句柄)，该句柄上存放的是连接句柄和其它类型句柄的关联信息。 当该句柄调用 DCITransCommit 或 DCITransRollback 函数提交或回滚时将会影响该句柄所在环境句柄上 的所有语句句柄 SQL 操作。 – DCI_HTYPE_STMT 分配一个 DCIStmt 结构句柄 (语句句柄)，分配该句柄时，环境句柄上必须已经分配了连接句柄并已经建 立了连接。可以在一个环境句柄上分配多个语句句柄，每个语句句柄可以进行独立的 SQL 操作。 – DCI_HTYPE_DESCRIBE 22 第 4 章 DCI 函数 分配一个 DCIDescribe 结构句柄 (描述对象句柄)，该句柄可以用来描述某个数据库中的对象，如表，存储 过程等。通过这个句柄，可以得到对象的具体信息，如表结构中的每个列信息，存储过程中的每个参数信 息。 – DCI_HTYPE_ERROR 分配一个 DCIError 结构句柄 (错误描述句柄)，该句柄存放每次 DCI 操作失败的原因，通过调用 DCIErrorGet 函数可以获取到这些信息。 – DCI_HTYPE_DIRPATH_CTX 分配一个 DCIDirPathCtx 结构句柄 (直接文件操作环境上下文)。 – DCI_HTYPE_DIRPATH_COLUMN_ARRAY 分配一个 DCIDirPathColArray 结构句柄（数据数组描述符）。 – DCI_HTYPE_DIRPATH_STREAM 分配一个 DCIDirPathStream 结构句柄 (数据流描述符)。 • xtramem_sz(输入) 保留参数，目前不使用。 • usrmempp(输出) 保留参数，目前不使用。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 需要注意的是调用该函数分配句柄成功以后，必须调用 DCIHandleFree 来释放这个句柄。当该函数调用失败 时，失败信息会存放在环境句柄中，可以通过调用 DCIErrorGet 接口并指定句柄类型为 DCI_HTYPE_ENV 来获 取失败的原因。 4.5 DCIHandleFree 函数原型： sword DCIHandleFree(void *hndlp, ub4 type ); 功能描述： 释放已分配的各类句柄，用于结束当前会话、断开与数据库的连接后的句柄清理。 参数说明： 23 第 4 章 DCI 函数 • hndlp(输入) 需要释放的句柄。 • type(输入) 指定需要释放的句柄类型。参见 DCIHandleAlloc 函数说明的 type 参数。 返回值： 如 果 释 放 成 功， 返 回 DCI_SUCCESS， 失 败 返 回 DCI_ERROR， 如 果 hndlp 指 向 的 句 柄 无 效， 返 回 DCI_INVALID_HANDLE。 注释： DCIHandleFree 函数需要和 DCIHandleAlloc 函数配合使用。 4.6 DCIServerVersion 函数原型： sword DCIServerVersion(void *hndlp, DCIError *errhp, DciText *bufp, ub4 bufsz, ub4 hndltype) 功能描述： 返回 Kingbase 服务器版本号。 参数说明： • hndlp(输入) DCISvcCtx 上下文句柄。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • bufp(输出) 服务器版本信息。 • bufsz(输入) 服务器版本信息 bufp 的长度 (字节)。 • hndltype(输入) hndlp 的句柄类型：DCI_HTYPE_SVCCTX 24 第 4 章 DCI 函数 返回值： 如 果 获 取 成 功， 返 回 DCI_SUCCESS， 失 败 返 回 DCI_ERROR， 如 果 hndlp 指 向 的 句 柄 无 效， 返 回 DCI_INVALID_HANDLE。 4.7 DCIServerAttach 函数原型： sword DCIServerAttach (DCIServer *srvhp, DCIError *errhp, CONST DciText *dblink, sb4 dblink_len, ub4 mode) 功能描述： 将一个数据库服务挂载到一个指定的连接句柄上。 参数说明： • srvhp(输入) 连接句柄指针，该句柄将会跟输入的服务名相关联。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • dblink(输入) 要关联的数据库服务名。该服务名需要在 DCI 的配置文件中配置。 • dblink_len(输入) 数据库服务名的长度。 • mode(输入) 附加模式，取值如下： – DCI_DEFAULT：缺省模式 – DCI_THREADED：多线程模式 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 调用该函数以后，可以调用 DCIServerDetach 函数解除连接和服务名之间的关联。 25 第 4 章 DCI 函数 4.8 DCIServerDetach 函数原型： sword DCIServerDetach (DCIServer *srvhp, DCIError *errhp, ub4 mode) 功能描述： 解除连接句柄和数据库服务名之间的关联。 参数说明： • srvhp(输入) 连接句柄，该句柄将会被解除与数据库服务名的关联。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • mode(输入) 附加模式，取值如下： – DCI_DEFAULT：缺省模式 – DCI_THREADED：多线程模式 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.9 DCISessionBegin 函数原型： sword DCISessionBegin(DCISvcCtx *svchp, DCIError *errhp, DCISession *usrhp, ub4 credt, ub4 mode) 功能描述： 使用登录信息在指定的连接类句柄上打开与数据库服务的连接。 参数说明： 26 第 4 章 DCI 函数 • svchp(输入) 指定打开连接的上下文，在这之前，上下文必须已经被关联了连接句柄。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • usrhp(输入) 登录信息句柄，执行登录之前，该句柄上必须已经设置了登录的用户名和口令。 • credt(输入) 登录的方式，目前只支持 DCI_CRED_RDBMS –通过用户名和口令与数据库服务建立起连接。 • mode(输入) 连接模式，取值如下： – DCI_DEFAULT：缺省模式 – DCI_THREADED：多线程模式 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 调用此方法建立连接以后，必须通过调用 DCISessionEnd 来结束这个连接。 4.10 DCISessionEnd 函数原型： sword DCISessionEnd (DCISvcCtx *svchp, DCIError *errhp, DCISession *usrhp, ub4 mode) 功能描述： 结束 DCISessionBegin 函数中连接类句柄与数据库服务之间的连接。 参数说明： • svchp(输入) 指定断开连接的上下文。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 27 第 4 章 DCI 函数 • usrhp(输入) 登录信息句柄。 • mode(输入) 连接模式，取值如下： – DCI_DEFAULT：缺省模式 – DCI_THREADED：多线程模式 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 在解除关联之前，如果连接上存在未提交的事务，那么解除连接后将全部回滚。 4.11 DCILogon 函数原型： sword DCILogon (DCIEnv *envhp, DCIError *errhp, DCISvcCtx **svchp, CONST DciText *username, ub4 uname_len, CONST DciText *password, ub4 passwd_len, CONST DciText *dbname, ub4 dbname_len) 功能描述： 根据数据库服务名、用户名和密码，登录到一个指定的数据库服务上，并初始化相关的上下文句柄。 参数说明： • envhp(输入) 操作所在的环境句柄，如果未指定上下文句柄，那么该函数在建立登录连接以后，会在该句柄上自动分配一个 上下文句柄。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • svchp(输入/输出) 28 第 4 章 DCI 函数 如果指定的上下文句柄非空，那么在登录以后，会自动设置相关的连接句柄到该句柄上。如果指定的上下文句 柄为空，那么 DCI 会自动分配一个上下文句柄输出，这个上下文句柄不需要通过调用 DCIHandleFree 来释放； 当应用调用 DCILogoff 以后，DCI 会自动释放这个句柄。 • username(输入) 登录的用户名。 • uname_len(输入) 登录的用户名长度。 • password(输入) 登录的口令。 • passwd_len(输入) 登录的口令长度。 • dbname(输入) 数据库服务名。 • dbname_len(输入) 数据库服务名长度。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 当连接建立以后，需要通过调用 DCILogoff 来断开连接。 4.12 DCILogon2 函数原型： sword DCILogon2(DCIEnv *envhp, DCIError *errhp, DCISvcCtx **svchp, CONST DciText *username, ub4 uname_len, CONST DciText *password, ub4 passwd_len, CONST DciText *dbname, ub4 dbname_len, ub4 mode) 29 第 4 章 DCI 函数 功能描述： 根据数据库服务名、用户名和密码，并根据传入的连接创建模式登录到一个指定的数据库服务上，并初始化相关 的上下文句柄。 参数说明： • envhp(输入) 操作所在的环境句柄，如果未指定上下文句柄，那么该函数在建立登录连接以后，会在该句柄上自动分配一个 上下文句柄。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • svchp(输入/输出) 如果指定的上下文句柄非空，那么在登录以后，会自动设置相关的连接句柄到该句柄上。如果指定的上下文句 柄为空，那么 DCI 会自动分配一个上下文句柄输出，这个上下文句柄不需要通过调用 DCIHandleFree 来释放； 当应用调用 DCILogoff 以后，DCI 会自动释放这个句柄。 • username(输入) 登录的用户名。 • uname_len(输入) 登录的用户名长度。 • password(输入) 登录的口令。 • passwd_len(输入) 登录的口令长度。 • dbname(输入) 数据库服务名。 • dbname_len(输入) 数据库服务名长度。 • mode(输入) 数据库连接的创建模式。 DCI_DEFAULT –等效于调用 DCILogon DCI_LOGON2_STMTCACHE –语句缓冲模式 DCI_LOGON2_CPOOL / DCI_CPOOL –连接池模式 DCI_LOGON2_SPOOL –会话池模式 DCI_LOGON2_PROXY –授权代理模式 30 第 4 章 DCI 函数 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 需要注意的是，该函数目前只支持以 DCI_DEFAULT 模式创建连接。 4.13 DCILogoff 函数原型： sword DCILogoff(DCISvcCtx *svchp, DCIError *errhp) 功能描述： 断开通过 DCILogon 与服务器建立的连接。 参数说明： • svchp(输入) 要断开连接的上下文句柄，该连接必须是通过 DCILogon 建立的。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 在断开连接之前，如果连接上存在未提交的事务，那么断开连接后将全部回滚。 4.14 DCIStmtPrepare 函数原型： sword DCIStmtPrepare (DCIStmt *stmtp, DCIError *errhp, DciText *stmt, ub4 stmt_len, ub4 language, ub4 mode) 31 第 4 章 DCI 函数 功能描述： 准备一条 SQL 语句，以便后续调用 DCIStmtExecute 来执行。 参数说明： • stmtp(输入) 用来准备执行的语句句柄。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • stmt(输入) 准备执行的 SQL 语句。 • stmt_len(输入) stmt 参数中 SQL 语句的长度。 • language 保留参数，目前不使用。 • mode(输入) 准备模式，取值如下： – DCI_DEFAULT：缺省模式 – DCI_THREADED：多线程模式 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 在调用该函数成功准备一条 SQL 以后，可以多次调用 DCIStmtExecute 执行这条 SQL 语句。如果在该函数执 行以后，对 SQL 上的参数或结果集进行了绑定操作，那么，只有在下一次调用该函数以后，这些绑定信息才会被解 除。SQL 语句的格式可以是单条 SQL，也可以是多条 SQL 组合成的一条语句。 4.15 DCIStmtExecute 函数原型： sword DCIStmtExecute (DCISvcCtx *svchp, DCIStmt *stmtp, DCIError *errhp, ub4 iters, ub4 rowoff, 32 第 4 章 DCI 函数 CONST DCISnapshot *snap_in, DCISnapshot *snap_out, ub4 mode) 功能描述： 执行通过 DCIStmtPrepare 准备后的语句。 参数说明： • svchp(输入) 执行所用的上下文句柄。 • stmtp(输入) 用来执行的语句句柄。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • iters(输入) 执行后影响的行数。对非查询语句，该参数表明一次性向服务器发送的数据行数，这个时候，该值必须大于等 于 1；对于查询语句，该参数表明一次性从服务器获取的结果集行数。应用程序必须在绑定行集时，申请足够 多的内存来接收返回的行集。 • rowoff(输入) 行集偏移。对于查询语句，该参数将被忽略；对于非查询语句，该参数表明向服务器发送多行数据时的起始偏 移行，从 0 开始计算。 • snap_in 保留参数，目前不使用。 • snap_out 保留参数，目前不使用。 • mode(输入) 执行的模式，可以是下面几种类型： – DCI_DESCRIBE_ONLY –描述模式 通过该模式描述准备好的语句 (并不执行语句)，从而得到语句的结果集元信息，应用程序可以通过调用 DCIAttrGet 函数来获取这些元信息，详细解释请参看下面将要提到的 DCIAttrGet 函数说明。另外，该 模式只对 DQL 语句有效，其他类型的语句在该模式下执行会报错。 – DCI_EXACT_FETCH –提取模式 当执行完以后，将会从结果集中提交 iters 参数指定的结果集行数到绑定的缓冲区。 33 第 4 章 DCI 函数 – DCI_COMMIT_ON_SUCCESS –自动提交模式 当 SQL 执行成功以后，会提交当前事务。 – DCI_DEFAULT –默认模式 等价于 DCI_EXACT_FETCH。 返回值： 如 果 执 行 成 功， 但 是 在 提 取 结 果 集 时 发 生 警 告 性 的 错 误 （字 符 串 截 断、 转 换 溢 出 等）， 那 么 返 回 DCI_SUCCESS_WITH_INFO，如果执行成功，但是结果集返回的行数小于 iters 参数所指定的行数，那么返 回 DCI_NO_DATA，其它正常情况下返回 DCI_SUCCESS，执行出错则返回 DCI_ERROR。 注释： 当函数返回 DCI_NO_DATA 时，并不是表示没有结果集返回，而是返回的结果集行数小于 iters 参数指定的行 数，并且结果集游标已经到达末尾。可以调用 DCIAttrGet 函数查看属性 DCI_ATTR_ROW_COUNT 的描述来获 取结果集中总共被提取的行数。 4.16 DCIStmtFetch 函数原型： sword DCIStmtFetch (DCIStmt *stmtp, DCIError *errhp, ub4 nrows, ub2 orientation, ub4 mode) 功能描述： 获取 SQL 生成的结果集中的行集。当执行一条查询以后，可以多次调用该函数来提取结果集中的数据行，直至 该函数返回 DCI_NO_DATA，说明已获得结果集中全部的数据行。 参数说明： • stmtp(输入) 用来提取结果集的语句句柄。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • nrows(输入) 一次操作需要获取的行数。 • orientation(输入) 行集提取的方式，可以有以下几种方式： 34 第 4 章 DCI 函数 – DCI_FETCH_NEXT –从结果集的当前游标位置向下进行提取操作。 – DCI_FETCH_FIRST –获取结果集的第一行，并开始向下进行提取操作。 – DCI_FETCH_LAST –获取结果集的最后一行，并开始向下进行提取操作。 – DCI_FETCH_PRIOR –从结果集的当前游标位置向上进行提取操作。 • mode(输入) 提取模式，取值如下： – DCI_DEFAULT：缺省模式 – DCI_THREADED：多线程模式 返回值： 如 果 执 行 成 功， 但 是 在 提 取 结 果 集 时 发 生 警 告 性 的 错 误 （字 符 串 截 断、 转 换 溢 出 等）， 那 么 返 回 DCI_SUCCESS_WITH_INFO，如果执行成功，但是结果集返回的行数小于 iters 参数所指定的行数，那么返 回 DCI_NO_DATA，其它正常情况下返回 DCI_SUCCESS，执行出错则返回 DCI_ERROR。 注释： 当函数返回 DCI_NO_DATA 时，并不是表示没有结果集返回，而是返回的结果集行数小于 iters 参数指定的行 数，并且结果集游标已经到达末尾。可以调用 DCIAttrGet 函数查看属性 DCI_ATTR_ROW_COUNT 的描述来获 取结果集中总共被提取的行数。 4.17 DCIStmtFetch2 函数原型： sword DCIStmtFetch2(DCIStmt *stmtp, DCIError *errhp, ub4 nrows, ub2 orientation, sb4 fetchOffset, ub4 mode) 功能描述： 获取 SQL 生成的结果集中的行集。当执行一条查询以后，可以多次调用该函数来提取结果集中的数据行，直至 该函数返回 DCI_NO_DATA，说明已获得结果集中全部的数据行。 参数说明： • stmtp(输入) 用来提取结果集的语句句柄。 35 第 4 章 DCI 函数 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • nrows(输入) 一次操作需要获取的行数。 • orientation(输入) 行集提取的方式，可以有以下几种方式： – DCI_DEFAULT –同 DCI_FETCH_NEXT，从当前游标位置向下进行提取操作 – DCI_FETCH_NEXT –从结果集的当前游标位置向下进行提取操作。 – DCI_FETCH_FIRST –获取结果集的第一行，并开始向下进行提取操作。 – DCI_FETCH_LAST –获取结果集的最后一行，并开始向下进行提取操作。 – DCI_FETCH_PRIOR –从结果集的当前游标位置向上进行提取操作。 – DCI_FETCH_ABSOLUTE –根据 fetchoffset 变量指定的绝对位置获取指定的行。 – DCI_FETCH_RELATIVE –根据 fetchoffset 变量指定的相对位置获取指定的行。 • fetchoffset(输入) 配合 orientation 变量使用的位移量，用于指定当前行的位置。 • mode(输入) 提取模式，取值如下： – DCI_DEFAULT：缺省模式 – DCI_THREADED：多线程模式 返回值： 如 果 执 行 成 功， 但 是 在 提 取 结 果 集 时 发 生 警 告 性 的 错 误 （字 符 串 截 断、 转 换 溢 出 等）， 那 么 返 回 DCI_SUCCESS_WITH_INFO，如果执行成功，但是结果集返回的行数小于 iters 参数所指定的行数，那么返 回 DCI_NO_DATA，其它正常情况下返回 DCI_SUCCESS，执行出错则返回 DCI_ERROR。 注释： 当函数返回 DCI_NO_DATA 时，并不是表示没有结果集返回，而是返回的结果集行数小于 iters 参数指定的行 数，并且结果集游标已经到达末尾。可以调用 DCIAttrGet 函数查看属性 DCI_ATTR_ROW_COUNT 的描述来获 取结果集中总共被提取的行数。 4.18 DCITransStart 函数原型： 36 第 4 章 DCI 函数 sword DCITransStart(DCISvcCtx *svchp, DCIError *errhp, uword timeout, ub4 flags) 功能描述： 开启事务。 参数说明： • svchp(输入) 要提交的上下文句柄。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • timeout 保留参数，目前不使用。 • flags 保留参数，目前不使用。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.19 DCITransCommit 函数原型： sword DCITransCommit(DCISvcCtx *svchp, DCIError *errhp, ub4 flags) 功能描述： 提交 (commit)SQL 的执行动作。 参数说明： • svchp(输入) 要提交的上下文句柄。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 37 第 4 章 DCI 函数 • flags 保留参数，目前不使用。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 需要注意的是，如果当前上下文句柄所属的环境句柄被分配了多个语句句柄，那么这种提交操作将会对所有的语 句句柄产生影响。 4.20 DCITransRollback 函数原型： sword DCITransRollback(DCISvcCtx *svchp, DCIError *errhp, ub4 flags) 功能描述： 回滚 (rollback)SQL 的执行动作。 参数说明： • svchp(输入) 要回滚的上下文句柄。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • flags 保留参数，目前不使用。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 需要注意的是，如果当前上下文句柄所属的环境句柄被分配了多个语句句柄，那么这种提交操作将会对所有的语 句句柄产生影响。 38 第 4 章 DCI 函数 4.21 DCIBindByName 函数原型： sword DCIBindByName(DCIStmt *stmtp, DCIBind **bindp, DCIError *errhp, CONST DciText *placeholder, sb4 placeh_len, dvoid *valuep, sb4 value_sz, ub2 dty, dvoid *indp, ub2 *alenp, ub2 *rcodep, ub4 maxarr_len, ub4 *curelep, ub4 mode) 功能描述： 按参数名称绑定 SQL 语句中的参数。 参数说明： • stmtp(输入) 绑定影响的语句句柄。 • bindp(输出) 输出的绑定信息句柄。可以通过该句柄调用 DCIBindArrayOfStruct 函数来设定该参数每行的间隔长度。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • placeholder(输入) 绑定的参数名称。 • placeh_len(输入) 参数名称的长度。 • valuep(输入) 参数值缓冲区指针。 • value_sz(输入) 参数类型单个值的最大大小，按字节计算。该参数为绑定参数可取值的最大长度，实际使用长度由 alenp 参数 指定。当 value_sz 的长度超过可绑定的最大长度值时，该值将在 DCI 内部被修改为可绑定的最大长度值。 39 第 4 章 DCI 函数 Kingbase DCI 的内部，在分片读写模式下，将大于 SB4MAX-100 到 SB4MAX 范围内的值用作识别分片读 写模式的标识值，故分片读写模式下可绑定的最大长度为 SB4MAX-100。非分片读写模式下的最大绑定长度为 SB4MAX。SB4MAX：有符号 4 字节整数最大值，值为 2 31 -1。 • dty(输入) 参数的数据类型。请参看 DCI 数据类型介绍。 • indp(输入) 指示器数组指针，指向一个 SB2 的数组，数组的大小和参数数组的大小一致。 • alenp(输入) 指定绑定值或绑定值数组中每个元素的实际长度，按字节计算。如果绑定值为数组且一次执行多行数据时，需 指定 alenp 为数组，alenp 数组中的每个值与绑定值数组中的值一一对应生效 (不指定 alenp 为数组则会发生不 可预知错误或异常)。 alenp 只针对绑定输入参数有效。 • rcodep(输入) 保留参数，目前不使用。 • maxarr_len(输入) 保留参数，目前不使用。 • curelep(输入) 保留参数，目前不使用。 • mode(输入) 绑定模式，取值如下： – DCI_DEFAULT：缺省模式 – DCI_THREADED：多线程模式 – DCI_DATA_AT_EXEC：分片读写模式 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 在 SQL 语句中使用冒号 + 参数名 (:NAME) 表示一个待绑定的参数，绑定动作需要在 SQL 语句的准备之后、 执行之前进行。需要注意的是，如果在执行的时候，iters 参数的数值必须大于 1, 并且没有显式调用 DCIBindArrayOfStruct 函数指定每个参数值的间隔大小，那么参数间隔就由 value_sz 参数的数值来决定。该函数支持通过一次绑 定操作同时绑定多个同名 (占位符名) 参数，绑定完成后，所有的同名占位符被绑定至同一变量。 40 第 4 章 DCI 函数 4.22 DCIBindByPos 函数原型： sword DCIBindByPos(DCIStmt *stmtp, DCIBind **bindp, DCIError *errhp, ub4 position, dvoid *valuep, sb4 value_sz, ub2 dty, dvoid *indp, ub2 *alenp, ub2 *rcodep, ub4 maxarr_len, ub4 *curelep, ub4 mode) 功能描述： 按参数在 SQL 语句中出现的位置进行绑定。 参数说明： • stmtp(输入) 绑定影响的语句句柄。 • bindp(输出) 输出的绑定信息句柄。可以通过该句柄调用 DCIBindArrayOfStruct 函数来设定该参数每行的间隔长度。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • position(输入) 参数在 SQL 中出现的位置，从 1 开始记数。 • valuep(输入) 参数值缓冲区指针。 • value_sz(输入) 参数类型单个值的最大大小，按字节计算。该参数为绑定参数可取值的最大长度，实际使用长度由 alenp 参数 指定。当 value_sz 的长度超过可绑定的最大长度值时，该值将在 DCI 内部被修改为可绑定的最大长度值。 Kingbase DCI 的内部，在分片读写模式下，将大于 SB4MAX-100 到 SB4MAX 范围内的值用作识别分片读 写模式的标识值，故分片读写模式下可绑定的最大长度为 SB4MAX-100。非分片读写模式下的最大绑定长度为 SB4MAX。SB4MAX：有符号 4 字节整数最大值，值为 2 31 -1。 41 第 4 章 DCI 函数 • dty(输入) 参数的数据类型。请参看 DCI 数据类型介绍。 • indp(输入) 指示器数组指针，指向一个 SB2 的数组，数组的大小和参数数组的大小一致。 • alenp(输入) 指定绑定值或绑定值数组中每个元素的实际长度，按字节计算。如果绑定值为数组且一次执行多行数据时，需 指定 alenp 为数组，alenp 数组中的每个值与绑定值数组中的值一一对应生效 (不指定 alenp 为数组则会发生不 可预知错误或异常)。 alenp 只针对绑定输入参数有效。 • rcodep(输入) 保留参数，目前不使用。 • maxarr_len(输入) 保留参数，目前不使用。 • curelep(输入) 保留参数，目前不使用。 • mode(输入) 绑定模式，取值如下： – DCI_DEFAULT：缺省模式 – DCI_THREADED：多线程模式 – DCI_DATA_AT_EXEC：分片读写模式 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 在 SQL 语句中使用冒号 + 参数名 (:NAME) 表示一个待绑定的参数，绑定动作需要在 SQL 语句的准备之后、 执行之前进行。该函数在绑定参数时，将忽略参数的名称，按它们在 SQL 中的位置一对一的绑定。需要注意的是， 如果在执行的时候，iters 参数的数值大于 1 并且没有显式调用 DCIBindArrayOfStruct 函数指定每个参数值的间隔大 小，那么参数间隔就由 value_sz 参数的数值来决定。 4.23 DCIBindDynamic 函数原型： 42 第 4 章 DCI 函数 sword DCIBindDynamic(DCIBind **bindp, DCIError *errhp, dvoid *ictxp, DCICallbackInBind icbfp, void *octxp, DCICallbackOutBind ocbfp) 功能描述： 按参数在 SQL 语句中出现的位置进行绑定。 参数说明： • bindp(输入/输出) 通过 DCIBindByName() 或者 DCIBindByPos() 函数返回的绑定信息句柄。 • errhp(输入/输出) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • ictxp(输入) icbfp 回调函数所需要的函数上下文指针。 • icbfp(输入) 运行时用于返回输入绑定参数值指针或者输入绑定数据片指针的用户回调函数。 • octxp(输入) ocbfp 回调函数所需要的函数上下文指针。 • ocbfp(输入) 运行时用于返回输出绑定参数值指针或者输出绑定数据片指针的用户回调函数。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 当函数 DCIBindByName() 或 DCIBindByPos() 调用模式为 DCI_DATA_AT_EXEC 时，后续才可通过该函数 注册提供或者接收数据的用户回调函数。 回调函数执行成功后必须返回 DCI_CONTINUE，任何不同于 DCI_CONTINUE 的返回值都代表着用户将立即 终止当前的处理。 4.24 DCIStmtGetBindInfo 函数原型： 43 第 4 章 DCI 函数 sword DCIStmtGetBindInfo (DCIStmt *stmtp, DCIError *errhp, ub4 size, ub4 startloc, sb4 *found, OraText *bvnp[], ub1 bvnl[], OraText *invp[], ub1 inpl[], ub1 dupl[], DCIBind *hndl[]) 功能描述： 获取绑定变量名或者指示器变量名。 参数说明： • stmtp(输入) DCIStmtPrepare() 返回的执行语句句柄。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • size(输入) 每个数组中的元素个数。 • startloc(输入) 获取绑定信息的起始绑定变量位置。 • found(输入) 该值的绝对值输出语句中相对于起始位置的绑定变量总个数。如果返回的绑定变量个数少于 size 变量传入的个 数，则为正值，否则为负值。 • bvnp(输出) 用于保存绑定变量名的数组。 • bvnl(输出) 用于保存绑定变量名长度的数组。 • invp(输出) 用于保存指示器变量名指针的数组。 • inpl(输出) 用于保存指示器变量名长度的指针数组。 44 第 4 章 DCI 函数 • dupl(输出) 一个元素值为 0 或 1 的数组，用于标识绑定位置是否与其他绑定位置重复。 • hndl(输出) 用于返回绑定句柄的数据，当前绑定位置已完成绑定操作时返回，重复绑定位置无返回。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 该函数需要在语句被准备好以后执行，以用于返回绑定变量的信息。如果语句没有绑定变量或者调用时指定的绑 定起始位置在语句中不存在，则返回 DCI_NO_DATA。该函数不返回 select into 列表中的变量信息，因为该列表中 的变量不被认为属于绑定变量。在调用该函数之前语句必须已被 DCIStmtPrepare() 调用准备好。 4.25 DCIBindArrayOfStruct 函数原型： sword DCIBindArrayOfStruct(DCIBind *bindp, DCIError *errhp, ub4 pvskip, ub4 indskip, ub4 alskip, ub4 rcskip) 功能描述： 指定参数绑定时，每个参数项中值的间隔大小，以字节计算。 参数说明： • bindp(输入) 参数绑定结构指针，它来自 DCIBindByName 或 DCIBindByPos 的参数绑定函数输出。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • pvskip(输入) 参数值下一个值的间隔长度。在多行绑定时，可以通过指定该参数来找到下一行值所在的位置。 • indskip(输入) 保留参数，目前不使用。 45 第 4 章 DCI 函数 • alskip(输入) 保留参数，目前不使用。 • rcskip(输入) 保留参数，目前不使用。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 该函数需要在调用执行动作之前调用。 4.26 DCICloseSvcSocket 函数原型： sword DCICloseSvcSocket(DCISvcCtx *svchp) 功能描述： 取消当前正在执行的语句。 参数说明： • svchp(输入) 服务上下文句柄。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 该函数 Oracle 中无原型。 4.27 DCIDefineByPos 函数原型： sword DCIDefineByPos(DCIStmt *stmtp, DCIDefine **defnp, DCIError *errhp, ub4 position, dvoid *valuep, 46 第 4 章 DCI 函数 sb4 value_sz, ub2 dty, dvoid *indp, ub2 *rlenp, ub2 *rcodep, ub4 mode) 功能描述： 按位置来指定查询返回结果集中每一列的存储空间。 参数说明： • stmtp(输入) 要绑定的语句句柄。 • defnp(输出) 绑定结构输出指针，可以通过使用该参数调用 DCIDefineArrayOfStruct 来指定该列每个值之间的间隔大小。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • position(输入) 绑定结果集中的列所在位置，从 1 开始计数。 • valuep(输入) 存放获取值的缓冲区指针。 • value_sz(输入) 单个该类型值的大小。 • dty(输入) 绑定的数据类型。 • indp(输入) 指示符缓冲区，如果结果集中存在 NULL 值，那么 DCI 会回填该缓冲区，把对应的位置置为 -1，其它情况下 置 0；如果在绑定的时候，未设置该指示符缓冲区，但是获取的结果中又存在 NULL 值，结果集提取时会返回 DCI_ERROR 的错误。 • rlenp(输入) 返回值长度指示缓冲区，如果返回值未发生截断，那么该缓冲区中的值就是实际的返回值长度；如果返回值 在获取的时候发生了截断，那么该缓冲区的值就是截断后的长度；如果返回值是空值，该缓冲区的值将被置为 0。 • rcodep(输入) 保留参数，目前不使用。 47 第 4 章 DCI 函数 • mode(输入) 绑定模式，取值如下： – DCI_DEFAULT：缺省模式 – DCI_THREADED：多线程模式 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 需要注意的是，该函数必须在 DCIStmtPrepare 之后调用，但是在调用 DCIStmtFetch 之前，可以随时动态的改 变绑定信息。 当 DCIStmtExecute 的 iters 参数大于 0 时，执行 select 语句，该操作需要在执行操作 (调用 DCIStmtExecute 方法) 之前调用。 4.28 DCIDefineArrayOfStruct 函数原型： sword DCIDefineArrayOfStruct (DCIDefine *defnp, DCIError *errhp, ub4 pvskip, ub4 indskip, ub4 rlskip, ub4 rcskip) 功能描述： 用来指定行集中每一列中每行值存储位置间隔的大小，以字节计算。 参数说明： • defnp(输入) 绑定结构指针，该参数是通过调用 DCIDefineByPos 后输出的。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • pvskip(输入) 每个值间隔的大小，在一次性返回多行时，DCI 会跟据这个大小回填每一行的值。 • indskip(输入) 空值指示符的间隔大小。 48 第 4 章 DCI 函数 • rlskip(输入) 返回值长度指示符的间隔大小。 • rcskip 保留参数，目前不使用。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 需要注意的是，如果要求一次性返回多行时，没有用该函数指定每行值的间隔大小，那么将会以 DCIDefineByPos 函数中 value_sz 参数的数值作为默认的间隔大小。 4.29 DCIDescriptorAlloc 函数原型： sword DCIDescriptorAlloc(CONST dvoid *parenth, dvoid **descpp, CONST ub4 type, CONST size_t xtramem_sz, dvoid **usrmempp) 功能描述： 为描述符分配存储空间。 参数说明： • parenth(输入) 环境句柄指针。 • descpp(输出) 存储描述符指针。 • type(输入) 描述符类型，目前支持： DCI_DTYPE_LOB –大字段描述。 DCI_DTYPE_PARAM –参数描述。 DCI_DTYPE_DATE –日期描述。 DCI_DTYPE_TIME –时间描述。 DCI_DTYPE_TIME_TZ –带时区的时间描述。 49 第 4 章 DCI 函数 DCI_DTYPE_TIMESTAMP –时间戳描述。 DCI_DTYPE_TIMESTAMP_LTZ –带本地时区的时间戳描述。 DCI_DTYPE_TIMESTAMP_TZ –带时区的时间戳描述。 DCI_DTYPE_INTERVAL_DS –时间间隔日和秒描述。 DCI_DTYPE_INTERVAL_YM –时间间隔年和月描述。 • xtramem_sz 保留参数，目前不使用。 • usrmempp 保留参数，目前不使用。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 通过该函数生成的描述符句柄需要通过调用 DCIDescriptorFree 来释放。 4.30 DCIDescriptorFree 函数原型： sword DCIDescriptorFree(dvoid CONST ub4 *descp, type) 功能描述： 释放 DCIDescriptorAlloc 生成的描述符。 参数说明： • descp(输入) 要释放的描述符指针。 • type(输入) 描述符类型，目前支持： DCI_DTYPE_LOB –大字段描述。 DCI_DTYPE_PARAM –参数描述。 DCI_DTYPE_DATE –日期描述。 DCI_DTYPE_TIME –时间描述。 50 第 4 章 DCI 函数 DCI_DTYPE_TIME_TZ –带时区的时间描述。 DCI_DTYPE_TIMESTAMP –时间戳描述。 DCI_DTYPE_TIMESTAMP_LTZ –带本地时区的时间戳描述。 DCI_DTYPE_TIMESTAMP_TZ –带时区的时间戳描述。 DCI_DTYPE_INTERVAL_DS –时间间隔日和秒描述。 DCI_DTYPE_INTERVAL_YM –时间间隔年和月描述。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 该函数只能释放通过 DCIDescriptorAlloc 生成的描述符。 4.31 DCILobAssign 函数原型： sword DCILobAssign(DCIEnv *envhp, DCIError *errhp, const DCILobLocator *src_locp, DCILobLocator **dst_lobcpp) 功能描述： 将一个 LobLocator 声明给另一个 LobLocator，该函数作用后，这两个 LobLocator 指向了同一个 Lob，但 LobLocator 内部是拷贝，不是引用。 参数说明： • envhp(输入) 环境句柄指针。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • src_locp(输入) 有效的非空 LobLocator 指针，将该 LobLocator 的值付给 dst_loccp。 • dst_lobcpp(输出) 有效的非空指向 LobLocator 地址的指针，src_locp 的 LobLocator 的值被赋给 dst_locpp 指向的 LobLocator。 51 第 4 章 DCI 函数 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.32 DCILobAppend 函数原型： sword DCILobAppend(DCISvcCtx *svchp, DCIError *errhp, DCILobLocator *dst_locp, DCILobLocator *src_locp) 功能描述： 将一个 LobLocator 指向的 Lob 值追加到另一个 LobLocator 指向的 Lob 值。 参数说明： • svchp(输入) 上下文句柄指针。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • dst_locp(输出) 非空的目的 LobLocator 指针，该指针的 Lob 类型必须与 src_locp 的 Lob 类型相同，且追加后，dst_locp 指 向的 Lob 值不能超出 Kingbase 允许的最大值，即 2GB。 • src_locp(输入) 非空的源 LobLocator 指针。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.33 DCILobCopy 函数原型： sword DCILobCopy(DCISvcCtx *svchp, DCIError *errhp, DCILobLocator *dst_locp, DCILobLocator *src_locp, 52 第 4 章 DCI 函数 ub4 amount, ub4 dst_offset, ub4 src_offset) 功能描述： 将一个 LobLocator 的 Lob 值的一部分，拷贝到另一个 LobLocator，Lob 类型必须相同。 参数说明： • svchp(输入) 上下文句柄指针。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • dst_locp(输出) 非空有效的目的 LobLocator 指针。 • src_locp(输入) 非空有效的源 LobLocator 指针。 • amount(输入) 该参数为 CLOB 字符数或者 BLOB 字节数，用于指定从 src_locp 指向的 Lob 中拷贝的长度。目前对于非 ASCII 编码的字符，仅支持 GBK 编码、UTF8 编码。 • dst_offset(输入) 该参数为 dst_locp 指向的目标 LobLocator 的绝对偏移量。对于 CLOB，值为从开始位置计算的字符数；对 于 BLOB，值为从开始位置计算的字节数，并由此开始写入。如果 dst_offset 超过了 Lob 本身的长度，则 LobLength 到 dst_offset 这部分被写入空格 (Clob) 或者 0(Blob)。 • src_offset(输入) 该参数为 src_locp 指向的源 LobLocator 的绝对偏移量。对于 CLOB，值为从开始位置计算的字符数；对于 BLOB，值为从开始位置计算的字节数。该 offset 从 1 开始。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.34 DCILobEnableBuffering 函数原型： 53 第 4 章 DCI 函数 sword DCILobEnableBuffering(DCISvcCtx *svchp, DCIError *errhp, DCILobLocator *locp) 功能描述： 开启 LobLacotor 缓存功能。已经开启了缓存功能的 LobLocator，再次开启则返回错误。 参数说明： • svchp(输入) 上下文句柄指针。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • locp(输入) 有效非空的 LobLocator 指针。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.35 DCILobDisableBuffering 函数原型： sword DCILobDisableBuffering(DCISvcCtx *svchp, DCIError *errhp, DCILobLocator *locp) 功能描述： 关闭 Lob 缓存功能。该函数并不能显式的更新 LobLocator，必须显式的调用 DCILobFlushBuffer()。 参数说明： • svchp(输入) 上下文句柄指针。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • locp(输入) 有效非空的 LobLocator 指针。 54 第 4 章 DCI 函数 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.36 DCILobErase 函数原型： sword DCILobErase(DCISvcCtx *svchp, DCIError *errhp, DCILobLocator *locp, ub4 *amount, ub4 offset) 功能描述： 从 LobLocator 指向 Lob 的某个偏移开始擦写一定的字节数; 对于 Blob，擦写成 0，对于 Clob，则擦写成空格。 参数说明： • svchp(输入) 上下文句柄指针。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • locp(输入) 有效非空的 LobLocator 指针。 • amount(输入输出) 该参数为 CLOB 字符数或者 BLOB 字节数，用于指定或返回擦写的 LOB 长度。作为输入时，传入待擦写的长 度；作为输出时，返回实际的擦写长度，因为实际可擦写的 LOB 长度可能不足，此时返回实际的擦写长度。目 前对于非 ASCII 编码的字符，仅支持 GBK 编码、UTF8 编码。 • offset(输入) 从 LobLocator 指向 lob 的偏移 offset 开始。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.37 DCILobFlushBuffer 函数原型： 55 第 4 章 DCI 函数 sword DCILobFlushBuffer(DCISvcCtx *svchp, DCIError *errhp, DCILobLocator *locp, ub4 flag) 功能描述： 将缓存 Buffer 中的值写入 Lob 字段。必须已经开启了 Lob 缓存功能，才可以使用该函数。 参数说明： • svchp(输入) 上下文句柄指针。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • locp(输入) 有效非空的 LobLocator 指针。 • flag(输入) 若传入的为 DCI_LOB_BUFFER_FREE 则 Lob 的 buffer 被释放掉。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.38 DCILobIsEqual 函数原型： sword DCILobIsEqual(DCIEnv *envhp, const DCILobLocator *x, const DCILobLocator *y, boolean *is_equal) 功能描述： 比较两个 LobLocator 指向的 Lob 是否相等，只有他们引用的是同一 Lob 才相等，若其中的 LobLocator 有为空 的，则认为不等。 参数说明： • envhp(输入) 环境句柄指针。 56 第 4 章 DCI 函数 • x(输入) 有效非空的 LobLocator 指针。 • y(输入) 有效非空的 LobLocator 指针。 • is_equal(输出) 如果相等，则返回 TRUE，否则返回 FALSE。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.39 DCILobLocatorIsInit 函数原型： sword DCILobLocatorIsInit(DCIEnv DCIError *envhp, *errhp, const DCILobLocator *locp, boolean *is_initialized) 功能描述： LobLocator 是否被初始化。 参数说明： • envhp(输入) 环境句柄指针。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • locp(输入) 有效非空的 LobLocator 指针。 • is_initialized(输出) 如果已经初始化，则返回 TRUE，否则返回 FALSE。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 57 第 4 章 DCI 函数 4.40 DCILobCharSetForm 函数原型： sword DCILobCharSetForm(DCIEnv *envhp, DCIError *errhp, const DCILobLocator *locp, ub1 *csfrm) 功能描述： 返回 Loblocator 引用的字符集格式。 参数说明： • envhp(输入) 环境句柄指针。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • locp(输入) 有效非空的指向 LobLocator 的指针。 • csfrm (输出) 返回的 LobLocator 的字符集格式: – SQLCS_IMPLICIT - 默认的字符集格式 – SQLCS_NCHAR - NCHAR 字符集 ID 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.41 DCILobCharSetId 函数原型： sword DCILobCharSetId(DCIEnv *envhp, DCIError *errhp, const DCILobLocator *locp, ub2 *csid) 功能描述： 返回 Loblocator 引用的字符集 ID。 58 第 4 章 DCI 函数 参数说明： • envhp(输入) 环境句柄指针。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • locp(输入) 有效非空的指向 LobLocator 的指针。 • csid (输出) 返回的 LobLocator 的字符集 ID，Blob 返回的字符集 ID 为 0，因为 Binary 数据没有字符集信息。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.42 DCILobClose 函数原型： sword DCILobClose(DCISvcCtx *svchp, DCIError *errhp, DCILobLocator *locp ) 功能描述： 关闭已经打开的大对象 参数说明： • svchp(输入) 服务上下文句柄 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • locp(输入/输出) 有效非空的指向 LobLocator 的指针。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 59 第 4 章 DCI 函数 4.43 DCILobCreateTemporary 函数原型： sword DCILobCreateTemporary(DCISvcCtx *svchp, DCIError *errhp, DCILobLocator *locp, ub2 csid, ub1 csfrm, ub1 lobtype, boolean cache, DCIDuration duration) 功能描述： 创建一个临时大对象。 参数说明： • svchp(输入) 服务上下文句柄 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • locp(输入/输出) 有效非空的指向 LobLocator 的指针。 • csid (输入) LobLocator 的字符集 ID，请传入 DCI_DEFAULT。 • csfrm (输入) 大对象的缓冲区字符集。不支持 SQLCS_NCHAR。 • lobtype (输入) 大对象的类型。支持 DCI_TEMP_BLOB 或 DCI_TEMP_CLOB。 • cache (输入) 保留字段，暂未使用。 • duration (输入) 保留字段，暂未使用。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 60 第 4 章 DCI 函数 4.44 DCILobFreeTemporary 函数原型： sword DCILobFreeTemporary( DCISvcCtx *svchp, DCIError *errhp, DCILobLocator *locp) 功能描述： 释放一个临时大对象。 参数说明： • svchp(输入) 服务上下文句柄 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • locp(输入/输出) 有效非空的指向 LobLocator 的指针。该 Locator 指向的大对象在数据库中将被释放。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.45 DCILobIsTemporary 函数原型： sword DCILobIsTemporary(DCIEnv *envhp, DCIError *errhp, DCILobLocator *locp, boolean *is_temporary) 功能描述： 判断一个大对象描述符指向的大对象是不是临时大对象 参数说明： • envhp(输入) 环境句柄 • errhp(输入) 61 第 4 章 DCI 函数 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • locp(输入) 有效非空的指向 LobLocator 的指针。 • is_temporary(输出) TRUE 表示是临时大对象，FALSE 表示不是临时大对象。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.46 DCILobIsOpen 函数原型： sword DCILobIsOpen(DCISvcCtx *svchp, DCIError *errhp, DCILobLocator *locp, boolean *flag ) 功能描述： 判断一个大对象描述符是否指向一个已经打开的大对象 参数说明： • svchp(输入) 服务上下文句柄 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • locp(输入) 有效非空的指向 LobLocator 的指针。 • flag(输出) TRUE 表示大对象已经打开，FALSE 表示没有打开。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 62 第 4 章 DCI 函数 4.47 DCILobTrim 函数原型： sword DCILobTrim(DCISvcCtx *svchp, DCIError *errhp, DCILobLocator *locp, ub4 newlen) 功能描述： 截断 Lob 的值。 参数说明： • svchp(输入) 上下文句柄指针。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • locp(输入) 指向 LobLocator 的指针, 该 Lob 的值将被截断。 • newlen(输入) LOB 值截断后的长度，该值必须小于等于截断前的长度。对于 Clob 为字符数，对于 Blob 则为字节数。目前对 于非 ASCII 编码的字符，仅支持 GBK 编码、UTF8 编码。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.48 DCILobGetLength 函数原型： sword DCILobGetLength (DCISvcCtx *svchp, DCIError *errhp, DCILobLocator *locp, ub4 *lenp) 功能描述： 返回大字段的大小，对于 CLOB，其为字符数；对于 BLOB，其为字节数。 参数说明： 63 第 4 章 DCI 函数 • svchp(输入) 上下文句柄指针。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • locp(输入) 存储大字段描述符指针。 • lenp(输出) 输出时，用于返回非空 LOB 对象的长度。对于 CLOB，其为字符数；对于 BLOB，其为字节数。目前对于非 ASCII 编码的字符，仅支持 GBK 编码、UTF8 编码。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.49 DCILobOpen 函数原型： sword DCILobOpen(DCISvcCtx *svchp, DCIError *errhp, DCILobLocator *locp, ub1 mode ) 功能描述： 打开一个大对象 参数说明： • svchp(输入) 上下文句柄指针。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • locp(输入/输出) 有效非空的指向 LobLocator 的指针 • mode(输入) DCI_LOB_READONLY / DCI_LOB_READWRITE. 64 第 4 章 DCI 函数 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.50 DCILobRead 函数原型： sword DCILobRead(DCISvcCtx *svchp, DCIError *errhp, DCILobLocator *locp, ub4 *amtp, ub4 offset, dvoid *bufp, ub4 bufl, dvoid *ctxp, sb4 (*cbfp)(dvoid *ctxp, CONST dvoid *bufp, ub4 len, ub1 piece), ub2 csid, ub1 csfrm) 功能描述： 读取某个大字段中指定长度的内容。 参数说明： • svchp(输入) 上下文句柄指针。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • locp(输入) 存储大字段描述符指针。 • amtp(输入/输出) 该参数为输入输出参数，当调用函数时，该参数表明想读取的 LOB 长度，当函数执行完以后，DCI 会回填实 际读到的 LOB 长度。对于 CLOB，长度为字节数或字符数，目前对于非 ASCII 编码的字符，仅支持 GBK 编 码、UTF8 编码；对于 BLOB，长度为字节数。 65 第 4 章 DCI 函数 表 4.50.1: DCILobRead() 函数的 amtp 参数为字节数或字符数说 明表 LOB 或 BFILE 输入 客户端定长字符集的输出 客户端变长字符集的输出 BLOB 和 BFILE 字节 字节 字节 CLOB 和 NCLOB 字符 字符 字节 • offset(输入) 输入时，该参数为从 LOB 开始位置到当前位置的绝对偏移量；对于 CLOB，值为从 LOB 开始位置的字符数， 目前对于非 ASCII 编码的字符，仅支持 GBK 编码、UTF8 编码；对于 BLOB，值为从 LOB 开始位置的字节 数；offset 取值从 1 开始。 • bufp(输入) 存放读到数据的缓冲区指针。 • bufl(输入) bufp 参数指向的缓冲区的大小。 • ctxp 保留参数，目前不使用。 • cbfp 注册的回调，可以在逐段读取中为每段调用。如果是 NULL，则为每块返回 DCI_NEED_DATA。 回调函数必须返回 DCI_CONTINUE 才能继续读取。如果返回任何其他错误代码，则将终止 LOB 读取。回调 采用以下参数： – ctxp 保留参数，目前不使用。 – bufp(输入/输出) 片段的缓冲区指针。 – len(输入) 当前片段在 bufp 中的长度 (以字节为单位)。 – piece(输入) 哪一块：DCI_FIRST_PIECE，DCI_NEXT_PIECE 或 DCI_LAST_PIECE • csid 保留参数，目前不使用。 • csfrm 保留参数，目前不使用。 66 第 4 章 DCI 函数 返回值： 如果执行成功，在还有数据未读取完的情况下，返回 DCI_NEED_DATA，如果数据都已经读完则返回 DCI_SUCCESS；执行失败则返回 DCI_ERROR。 注释： 目前只支持连续的只向前读操作。 4.51 DCILobRead2 函数原型： sword DCILobRead2 ( DCISvcCtx *svchp, DCIError *errhp, DCILobLocator *locp, ub8 *byte_amtp, ub8 *char_amtp, ub4 offset, dvoid *bufp, ub4 bufl, ub1 piece, dvoid *ctxp, DCICallbackLobRead cbfp, ub2 csid, ub1 csfrm); 功能描述： 读取某个大字段中指定长度的内容。 参数说明： • svchp(输入) 上下文句柄指针。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • locp(输入) 存储大字段描述符指针。 • byte_amtp(输入/输出) IN - 该参数表明想要读取的 LOB 字节数。对于 BLOB，该参数总是生效；对于 CLOB，只有当 char_amtp 参 数为 0 时该参数才生效。 OUT - 函数执行完以后，回填实际读到缓存中的字节数。 67 第 4 章 DCI 函数 • char_amtp(输入/输出) IN - 该参数表明想要读取到用户缓存区中的最大 LOB 字符数。对于 BLOB，该参数忽略。 OUT - 函数执行完以后，回填实际读到缓存中的字符数。对于 BLOB，未定义输出。 注意：目前对于非 ASCII 编码的字符，仅支持 GBK 编码、UTF8 编码。 • offset(输入) 从大字段开始位置到当前位置的偏移量，以字节为单位；offset 取值从 1 开始。 • bufp(输入/输出) 存放读到数据的缓冲区指针。 • bufl(输入) bufp 参数指向的缓冲区的大小。 • piece(输入) DCI_ONE_PIECE –调用从不假设轮询，如果指示的数据量比缓存的长度大，则尽可能向 buffer 中赋值。对 于轮询，首次调用需传入 DCI_FIRST_PIECE，后续调用需传入 DCI_NEXT_PIECE。在使用回调函数时应 传入 DCI_FIRST_PIECE。 • ctxp 保留参数，目前不使用 (仅用于和 Oracle 保持兼容) • cbfp 保留参数，目前不使用 (仅用于和 Oracle 保持兼容) • csid 保留参数，目前不使用 (仅用于和 Oracle 保持兼容) • csfrm 保留参数，目前不使用 (仅用于和 Oracle 保持兼容) 返回值： 如果执行成功，在还有数据未读取完的情况下，返回 DCI_NEED_DATA，如果数据都已经读完则返回 DCI_SUCCESS；执行失败则返回 DCI_ERROR。 注意： 目前只支持连续的只向前读操作。 4.52 DCILobWrite 函数原型： 68 第 4 章 DCI 函数 sword DCILobWrite(DCISvcCtx *svchp, DCIError *errhp, DCILobLocator *locp, ub4 *amtp, ub4 offset, dvoid *bufp, ub4 buflen, ub1 piece, dvoid *ctxp, sb4 (*cbfp)(dvoid *ctxp, dvoid *bufp, ub4 *len, ub1 *piece), ub2 csid, ub1 csfrm) 功能描述： 连续的写入内容到一个大字段存储描述符中。 参数说明： • svchp(输入) 上下文句柄指针。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • locp(输入) 存储大字段描述符指针。 • amtp(输入/输出) 该参数为输入输出参数，当调用函数时，该参数表明想写入数据库的 LOB 长度，当函数执行完以后，DCI 会回 填实际写入的 LOB 长度。对于 CLOB，长度为字节数或字符数，目前对于非 ASCII 编码的字符，仅支持 GBK 编码、UTF8 编码；对于 BLOB，长度为字节数。 表 4.52.1: DCILobWrite() 函数的 amtp 参数为字节数或字符数说 明表 LOB 或 BFILE 客户端定长字符集的输入 客户端变长字符集的输入 输出 BLOB 和 BFILE 字节 字节 字节 CLOB 和 NCLOB 字符 字节 字符 • offset(输入) 输入时，该参数为从 LOB 开始位置到当前位置的绝对偏移量；对于 CLOB，值为从 LOB 开始位置的字符数， 目前对于非 ASCII 编码的字符，仅支持 GBK 编码、UTF8 编码；对于 BLOB，值为从 LOB 开始位置的字节 69 第 4 章 DCI 函数 数；offset 取值从 1 开始。 • bufp(输入) 存放要写的数据缓冲区指针。 • bufl(输入) bufp 参数指向的缓冲区的大小。 • piece 正在写入缓冲区的哪一部分。此参数的默认值为 DCI_ONE_PIECE，表示将缓冲区写入单个块中。对于分段 或回调模式可使用这些值：DCI_FIRST_PIECE，DCI_NEXT_PIECE 和 DCI_LAST_PIECE。 • ctxp 保留参数，目前不使用。 • cbfp 注册的回调，可以在逐段写入中为每段调用。如果是 NULL，则使用标准轮询方法。 回调函数必须返回 DCI_CONTINUE 才能继续写入。如果返回任何其他错误代码，则 LOB 写入将终止。回调 采用以下参数： – ctxp 保留参数，目前不使用。 – bufp(输入/输出) 片段的缓冲区指针，这与传递给 DCILobWrite() 例程的 bufp 输入相同。 – len(输入/输出) (输入) 缓冲区中数据的长度，(输出) bufp 中当前数据的长度 (以字节为单位)。 – piece(输出) 哪一块：DCI_NEXT_PIECE 或 DCI_LAST_PIECE • csid 保留参数，目前不使用。 • csfrm 保留参数，目前不使用。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 你可以调用 DCIStmtFetch 来移动游标，以便对其它行的大字段进行写入操作。 70 第 4 章 DCI 函数 4.53 DCINumberAdd 函数原型： sword DCINumberAdd(DCIError *err, const DCINumber *number1, const DCINumber *number2, DCINumber *result ) 功能描述： 计算两个数的和。 参数说明： • err(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • number1(输入) 被加数 • number2(输入) 加数 • result(输出) 和 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： number1，number2 为空时，返回 DCI_ERROR。 4.54 DCINumberAssign 函数原型： sword DCINumberAssign(DCIError *err, const DCINumber *from, DCINumber *to ) 功能描述： 对 Number 进行赋值。 71 第 4 章 DCI 函数 参数说明： • err(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • from(输入) 源数 • to(输出) 目的数 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： from, to 为空时，返回 DCI_ERROR。 4.55 DCINumberDiv 函数原型： sword DCINumberDiv(DCIError *err, const DCINumber *number1, const DCINumber *number2, DCINumber *result ) 功能描述： 计算两个数的商。 参数说明： • err(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • number1(输入) 分子 • number2(输入) 分母 • result(输出) 商 72 第 4 章 DCI 函数 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： number1，number2 为空时，或出现除 0 错误时，返回 DCI_ERROR。 4.56 DCINumberIsInt 函数原型： sword DCINumberIsInt(DCIError *err, const DCINumber *number, boolean *result ) 功能描述： 判断一个数是不是整数。 参数说明： • err(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • number(输入) 待判断数 • result(输出) TRUE 表示是整数，FALSE 表示不是 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： number、result 为空时，返回 DCI_ERROR。 4.57 DCINumberMod 函数原型： sword DCINumberMod(DCIError const DCINumber *err, *number1, 73 第 4 章 DCI 函数 const DCINumber *number2, DCINumber *result ) 功能描述： 计算两个数的余数。 参数说明： • err(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • number1(输入) 分子 • number2(输入) 分母 • result(输出) 结果 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： number1，number2 为空时，或者出现除 0 错误时，返回 DCI_ERROR。 4.58 DCINumberMul 函数原型： sword DCINumberMul(DCIError *err, const DCINumber *number1, const DCINumber *number2, DCINumber *result ) 功能描述： 计算两个数的积。 参数说明： • err(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 74 第 4 章 DCI 函数 • number1(输入) 被乘数 • number2(输入) 乘数 • result(输出) 积 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： number1，number2 为空时，返回 DCI_ERROR。 4.59 DCINumberAbs 函数原型： sword DCINumberAbs(DCIError *err, const DCINumber *number, DCINumber *result ) 功能描述： 计算一个数的绝对值。 参数说明： • err(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • number(输入) 求绝对值数。 • result(输出) 绝对值结果。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： number 为空时，返回 DCI_ERROR。 75 第 4 章 DCI 函数 4.60 DCINumberNeg 函数原型： sword DCINumberNeg(DCIError *err, const DCINumber *number, DCINumber *result ) 功能描述： 对 DCI 数值取反。 参数说明： • err(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • number(输入) 取反的原输入数。 • result(输出) 取反后的结果数值。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 任一输入参数为空时，返回 DCI_ERROR。 4.61 DCINumberSub 函数原型： sword DCINumberSub(DCIError *err, const DCINumber *number1, const DCINumber *number2, DCINumber *result ) 功能描述： 计算两个数的差。 参数说明： • err(输入) 76 第 4 章 DCI 函数 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • number1(输入) 减数。 • number2(输入) 被减数。 • result(输出) 两个数的差。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： number1，number2 为空时，返回 DCI_ERROR。 4.62 DCIDescribeAny 函数原型： sword DCIDescribeAny (DCISvcCtx *svchp, DCIError *errhp, dvoid *objptr, ub4 objnm_len, ub1 objptr_typ, ub1 info_level, ub1 objtyp, DCIDescribe *dschp) 功能描述： 描述某个数据库对象，得到其内部构造的详细信息。 参数说明： • svchp(输入) 上下文句柄指针。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • objptr(输入) 要被描述的对象指针，目前只支持字符串类型指针。 77 第 4 章 DCI 函数 • objnm_len(输入) objptr 参数中字符串的长度。 • objptr_typ(输入) objptr 指针类型，目前只支持 DCI_OTYPE_NAME –对象名称类型指针。 • info_level 保留参数，目前不使用。 • objtyp(输入) objptr 参数所指的对象类型，可以为下面几种对象： – DCI_PTYPE_TABLE –表 – DCI_PTYPE_PROC –过程 – DCI_PTYPE_FUNC –函数 – DCI_PTYPE_PKG –对象包 • dschp(输入) 一个描述符句柄，该句柄可以通过使用 DCI_HTYPE_DESCRIBE 作为参数调用 DCIHandleAlloc 分配得到。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 调用该函数对某个对象进行描述以后，需要结合调用 DCIParamGet 和 DCIAttrGet 来获取描述后的信 息。通过该接口获取表中各列的元信息时，默认不会获取到隐藏列的元信息。可以通过 DCIAttrSet 接口设置 DCI_ATTR_SHOW_INVISIBLE_COLUMNS 属性，并将属性值设为 true 来获取隐藏列的元信息。 4.63 DCIParamGet 函数原型： sword DCIParamGet(CONST dvoid *hndlp, ub4 htype, DCIError *errhp, dvoid **parmdpp, ub4 pos) 功能描述： 返回描述句柄或语句句柄中的根据位置指定的参数描述符。 参数说明： 78 第 4 章 DCI 函数 • hndlp(输入) 一个存在描述信息的句柄。 • htype(输入) hndlp 参数句柄的类型，支持以下两种类型： – DCI_HTYPE_STMT –语句句柄 – DCI_DTYPE_PARAM –参数句柄 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • parmdpp(输出) 输出的描述符句柄，通过该句柄调用 DCIAttrGet 函数就可以得到指定位置上的描述信息。 • pos(输入) 要获取描述符上指定位置的描述信息。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.64 DCIAttrSet 函数原型： sword DCIAttrSet(dvoid *trgthndlp, ub4 trghndltyp, dvoid *attributep, ub4 size, ub4 attrtype, DCIError *errhp) 功能描述： 设置句柄上的属性值。 参数说明： • trgthndlp(输入) 需要设置属性的句柄指针。 • trghndltyp(输入) trgthndlp 参数句柄的类型，可以是以下几种类型： – DCI_HTYPE_SVCCTX 上下文句柄。 79 第 4 章 DCI 函数 – DCI_HTYPE_SESSION 连接信息句柄。 – DCI_HTYPE_STMT 语句句柄。 – DCI_HTYPE_DIRPATH_CTX 直接文件操作上下文。 – DCI_DTYPE_PARAM 参数信息句柄。 • attributep(输入) 要设置的属性值指针，下面是在各种属性的情况下，数据值的类型： – DCI_HTYPE_SVCCTX ∗ DCI_ATTR_SERVER –DCIServer 结构句柄 (连接句柄) ∗ DCI_ATTR_SESSION –DCISession 结构句柄 (连接信息句柄) – DCI_HTYPE_SESSION ∗ DCI_ATTR_USERNAME –字符串指针 (char*) ∗ DCI_ATTR_PASSWORD –字符串指针 (char*) – DCI_HTYPE_STMT ∗ DCI_ATTR_PREFETCH_ROWS –无符号整形指针 (ub4*) – DCI_HTYPE_DIRPATH_CTX ∗ DCI_ATTR_BUF_SIZE –无符号整形指针 (ub4*) ∗ DCI_ATTR_NAME –字符串指针 (char*) ∗ DCI_ATTR_NUM_COLS –无符号短整形指针 (ub2*) ∗ DCI_ATTR_SCHEMA_NAME –字符串指针 (char*) ∗ DCI_ATTR_DATEFORMAT –字符串指针 (char*)，如：YYYY-MM-DD ∗ DCI_ATTR_DIRPATH_INPUT –无符号单字节整形指针 (ub1*)， 目 前 只 支 持 DCI_DIRPATH_INPUT_STREAM 和 DCI_DIRPATH_INPUT_TEXT – DCI_DTYPE_PARAM ∗ DCI_ATTR_NAME –字符串指针 (char*) ∗ DCI_ATTR_DATA_TYPE –无符号短整形指针 (ub2*) ∗ DCI_ATTR_DATA_SIZE –无符号整形指针 (ub4*) ∗ DCI_ATTR_DATEFORMAT –字符串指针 (char*)，如：YYYY-MM-DD ∗ DCI_ATTR_PRECISION –无符号单字节整形指针 (ub1*) ∗ DCI_ATTR_SCALE –无符号单字节整形指针 (ub1*) – DCI_HTYPE_DESCRIBE ∗ DCI_ATTR_SHOW_INVISIBLE_COLUMNS –设置描述符是否描述隐藏列信息 (ub1) 80 第 4 章 DCI 函数 • size(输入) attributep 参数的大小，如果 attributep 参数指针是一个字符串类型指针，那么 size 就是该字符串的实际长度； 如果 attributep 参数是其它类型指针，则忽略该参数。 • attrtype(输入) 要设置的句柄属性。不同类型的句柄有着不同的属性： – DCI_HTYPE_SVCCTX ∗ DCI_ATTR_SERVER –在上下文句柄上附加一个连接句柄 ∗ DCI_ATTR_SESSION –在上下文句柄上附加一个连接信息句柄 – DCI_HTYPE_SESSION ∗ DCI_ATTR_USERNAME –在连接信息句柄上设置登录的用户名 ∗ DCI_ATTR_PASSWORD –在连接信息句柄上设置登录的口令 – DCI_HTYPE_STMT ∗ DCI_ATTR_PREFETCH_ROWS –在语句句柄上设置预取的结果集行数 – DCI_HTYPE_DIRPATH_CTX ∗ DCI_ATTR_BUF_SIZE –直接文件操作时缓冲区的大小 ∗ DCI_ATTR_NAME –直接文件操作时针对的表名 ∗ DCI_ATTR_NUM_COLS –直接文件操作时针对的表的列数 ∗ DCI_ATTR_SCHEMA_NAME –直接文件操作时针对的表所在的模式名 ∗ DCI_ATTR_DATEFORMAT –直接文件操作时日期格式表达式 ∗ DCI_ATTR_DIRPATH_INPUT –直接文件操作时数据流的形式 – DCI_DTYPE_PARAM ∗ DCI_ATTR_NAME –直接文件操作时设置列的名称 ∗ DCI_ATTR_DATA_TYPE –直接文件操作时设置列的数据类型 ∗ DCI_ATTR_DATA_SIZE –直接文件操作时设置列的数据类型大小，以字节计 ∗ DCI_ATTR_DATEFORMAT –直接文件操作时设置的日期格式表达式 ∗ DCI_ATTR_PRECISION –直接文件操作时设置列的精度 ∗ DCI_ATTR_SCALE –直接文件操作时设置列的刻度 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 81 第 4 章 DCI 函数 4.65 DCIAttrGet 函数原型： sword DCIAttrGet(CONST dvoid *trgthndlp, ub4 trghndltyp, dvoid *attributep, ub4 *sizep, ub4 attrtype, DCIError *errhp) 功能描述： 获取句柄上的属性值。 参数说明： • trgthndlp(输入) 要获取属性的句柄。 • trghndltyp(输入) trgthndlp 参数中的句柄类型，可以有以下几种类型： – DCI_DTYPE_PARAM –参数句柄 – DCI_HTYPE_STMT –语句句柄 – DCI_HTYPE_DESCRIBE –描述符句柄 – DCI_HTYPE_DIRPATH_CTX –直接文件操作句柄 – DCI_HTYPE_DIRPATH_COLUMN_ARRAY –直接文件数据数组句柄 – DCI_HTYPE_DIRPATH_STREAM –直接文件数据流句柄 • attributep(输出) 存放输出属性的缓冲区。如果输入的属性为字符串，那么该参数值应是字符串指针的地址，应用应当及时的复 制其值到自己定义的缓冲区中。 • sizep(输出) 存放输出属性大小的缓冲区，如果输出属性是字符串，那么它的值是字符串的实际长度，否则该大小是实际输 出值的大小，按字节计算。 • attrtype(输入) 要获取的属性。不同类型的句柄有着不同的属性可以获取，请参照样例。 下面是 attrtype 在不同的输入句柄上的属性取值: – DCI_DTYPE_PARAM ∗ DCI_HTYPE_RESULT_COL_ATTR 82 第 4 章 DCI 函数 · DCI_ATTR_DATA_SIZE –列的数据类型大小 (ub2) · DCI_ATTR_DATA_TYPE –列的数据类型 (ub2) · DCI_ATTR_DISP_SIZE –列的显示大小 (ub2) · DCI_ATTR_NAME –列名 (char*) · DCI_ATTR_PRECISION –列的精度 (ub2) · DCI_ATTR_SCALE –列的刻度 (ub1) · DCI_ATTR_IS_NULL –列是否允许为空 (ub1) · DCI_ATTR_INVISIBLE_COL –列是否为隐藏列 (ub1) · DCI_ATTR_REF_TDO –对象类型的本地 REF 索引 ∗ DCI_PTYPE_TABLE · DCI_ATTR_OBJID –表的 ID 号 (ub4) · DCI_ATTR_NUM_COLS –表中的列数 (ub2) · DCI_ATTR_LIST_COLUMNS –表中列信息的描述参数句柄 (void*) ∗ DCI_ATTR_LIST_COLUMNS · 同 DCI_HTYPE_RESULT_COL_ATTR 属性 ∗ DCI_PTYPE_PROC · DCI_ATTR_DATA_SIZE –参数的数据类型大小 (ub2) · DCI_ATTR_DATA_TYPE –参数的数据类型 (ub2) · DCI_ATTR_DISP_SIZE –参数的显示大小 (ub2) · DCI_ATTR_NAME –参数名 (char*) · DCI_ATTR_PRECISION –参数的精度 (ub1) · DCI_ATTR_SCALE –参数的刻度 (ub1) · DCI_ATTR_NUM_PARAMS –参数的个数 (ub2) · DCI_ATTR_LIST_ARGUMENTS –参数的描述参数句柄 (void*) ∗ DCI_PTYPE_FUNC · 同 DCI_PTYPE_PROC ∗ DCI_PTYPE_PKG –包中信息的描述参数句柄 (void*) ∗ DCI_ATTR_LIST_SUBPROGRAMS · DCI_ATTR_LIST_ARGUMENTS –参数的描述参数句柄 (void*) · DCI_ATTR_NAME –包中的过程名者是函数名 (char*) · DCI_ATTR_PTYPE –对象类型：DCI_PTYPE_PROC 或 DCI_PTYPE_FUNC 83 第 4 章 DCI 函数 · DCI_ATTR_NUM_PARAMS –包中对象的个数 (ub2) ∗ DCI_PTYPE_LIST · DCI_ATTR_NAME –直接文件操作时设置列的名称 (char*) · DCI_ATTR_DATA_TYPE –直接文件操作时设置列的数据类型 (ub2) · DCI_ATTR_DATA_SIZE –直接文件操作时设置列的数据类型大小 (ub2) · DCI_ATTR_DATEFORMAT –直接文件操作时设置的日期格式表达式 (char*) · DCI_ATTR_PRECISION –直接文件操作时设置列的精度 (ub1) · DCI_ATTR_SCALE –直接文件操作时设置列的刻度 (ub1) – DCI_HTYPE_STMT ∗ DCI_ATTR_PREFETCH_ROWS –当前一次性返回结果集记录的行数 (ub4) ∗ DCI_ATTR_NUM_COLS –结果集中列的个数 (ub2) ∗ DCI_ATTR_ROW_COUNT –已经返回记录的总行数 (ub4) – DCI_HTYPE_DESCRIBE ∗ DCI_PTYPE_TABLE –返回描述表中各列信息的参数句柄 (void*) ∗ DCI_PTYPE_PROC –返回描述存储过程中参数的参数句柄 (void*) ∗ DCI_PTYPE_FUNC –返回描述存储函数中参数的参数句柄 (void*) ∗ DCI_PTYPE_PKG –返回描述包中信息的参数句柄 (void*) – DCI_HTYPE_DIRPATH_CTX ∗ DCI_ATTR_BUF_SIZE –当前文件操作的缓冲区大小 (ub4)，默认是 64K ∗ DCI_ATTR_NAME –当前操作的表名 (char*) ∗ DCI_ATTR_NUM_COLS –当前操作的列数 (ub2) ∗ DCI_ATTR_NUM_ROWS –当前允许一次性操作的行数 (ub4) ∗ DCI_ATTR_SCHEMA_NAME –操作的表所在的模式名 (char*) ∗ DCI_ATTR_DATEFORMAT –当前设置的时间日期格式表达式 (char*) ∗ DCI_ATTR_LIST_COLUMNS –返回描述表中各列信息的参数句柄 (void*) ∗ DCI_ATTR_DIRPATH_INPUT –当前数据流的类型，是文本还是二进制 (ub1) – DCI_HTYPE_DIRPATH_COLUMN_ARRAY ∗ DCI_ATTR_NUM_ROWS –当前缓冲区允许一次性最大设置的记录行数 (ub4) ∗ DCI_ATTR_NUM_COLS –当前缓冲区中的列数 (ub2) ∗ DCI_ATTR_ROW_COUNT –转换成功的行数 (ub4) ∗ DCI_ATTR_COL_COUNT –转换成功的列数 (ub2) 84 第 4 章 DCI 函数 – DCI_HTYPE_DIRPATH_STREAM ∗ DCI_ATTR_NUM_ROWS –数据流中的行数 (ub4) ∗ DCI_ATTR_NUM_COLS –数据流中的行数 (ub2) ∗ DCI_ATTR_ROW_COUNT –转换成功的行数 (ub4) ∗ DCI_ATTR_COL_COUNT –转换成功的列数 (ub2) ∗ DCI_ATTR_BUF_ADDR –数据流缓冲区地址 (void*) ∗ DCI_ATTR_BUF_SIZE –数据流缓冲区的大小 (ub4) • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.66 DCIObjectPin 函数原型： sword DCIObjectPin(DCIEnv *env, DCIError *err, DCIRef *object_ref, DCIComplex *corhdl, DCIPinOpt pin_option, DCIDuration pin_duration, DCILockOpt lock_option, void **object); 功能描述： 固定一个可引用的对象。 参数说明： • env(输入/输出) 以对象模式初始化的 DCI 环境句柄。 • err(输入/输出) DCI 错误句柄。出错时错误记录在 err 中，通过调用 DCIErrorGet() 获取诊断信息。 • object_ref (输入) 对对象的引用。 85 第 4 章 DCI 函数 • corhdl(输入) 复杂对象检索句柄。 • pin_option(输入) 指定要检索的对象的副本类型。 DCI_PIN_ANY –如果对象已经在对象缓存中，则返回这个对象。否则，从数据库中检索对象。当客户端知道 连接会话中的数据具有独占访问权时，此选项很有用。 • pin_duration(输入) 客户端访问对象的持续时间，目前不使用 (仅用于和 Oracle 保持兼容)。 • lock_option(输入) 锁选项（例如，独占），目前不使用 (仅用于和 Oracle 保持兼容)。 • object(输出) 指向固定对象的指针。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 当给定对象引用时，此函数固定一个可引用的对象实例。固定过程有两个目的： • 在给定引用的情况下定位对象。这是由对象缓存中能够跟踪对象的对象缓存完成的。 • 通知对象缓存一个持久对象正在被使用，因此该持久对象不可以被期退。由于可以在需要时从服务器加载持久 对象，所以如果可以在分配持续时间到期之前释放（期退）完全未固定的持久对象，则可以增加内存利用率。 一个对象可以被固定多次。固定的对象会一直保留在内存中，直到完全取消固定为止。 4.67 DCIObjectUnpin 函数原型： sword DCIObjectUnpin ( DCIEnv *env, DCIError *err, void *object); 功能描述： 取消固定对象。 参数说明： • env(输入/输出) 以对象模式初始化的 DCI 环境句柄。 86 第 4 章 DCI 函数 • err(输入/输出) DCI 错误句柄。出错时错误记录在 err 中，通过调用 DCIErrorGet() 获取诊断信息。 • object(输入) 必须是指向已固定对象的指针。 返回值： 返回 DCI_SUCCESS，重置成功。返回 DCI_ERROR，表示出错。 注释： 每个对象都有一个相关联的 pin 计数，每当一个对象被固定时，该计数就会增加；当对象的 pin 计数为零时，该 对象即为完全取消固定。DCI 可以随时隐式释放未固定的对象而不会出错。 该函数用于取消固定对象。当以下任意一项为真时，对象将完全取消固定： • 对象的 pin 计数达到零（即，在总共固定 n 次后，它总共取消固定 n 次）。 • 对象的 pin 持续时间结束。 • 函数 DCIObjectPinCountReset() 在对象上被调用。 当对象完全取消固定时，DCI 可以随时隐式释放它而不会发生错误。 以下规则适用于取消固定不同类型的对象： 对于持久对象 当持久对象完全取消固定时，它就成为期退的候选对象，对象的内存在过期时会被释放。期退有利于最大 化内存的利用率。dirty 对象不能被期退直到它被刷新至服务端。 对于瞬态对象（暂不支持） 对象的引脚数递减。瞬态对象只能在其分配持续时间结束时或通过调用显式删除时被释放 DCIObjectFree()。 对于值（暂不支持） 此函数返回错误。 4.68 DCIObjectPinCountReset 函数原型： sword DCIObjectPinCountReset ( DCIEnv *env, DCIError *err, void *object); 功能描述： 87 第 4 章 DCI 函数 完全取消固定对象，将其针数设置为零。 参数说明： • env(输入/输出) 以对象模式初始化的 DCI 环境句柄。 • err(输入/输出) DCI 错误句柄。出错时错误记录在 err 中，通过调用 DCIErrorGet() 获取诊断信息。 • object(输入) 必须是指向已固定对象的指针。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 此函数完全取消固定对象，将其针数设置为零。当一个对象完全取消固定时，DCI 可以随时隐式释放它而不会出 错。以下规则适用于特定对象类型： 对于持久对象 当持久对象完全取消固定时，它就成为期退的候选对象，对象的内存在过期时被释放。期退有利于最大化 内存的利用率。Dirty 对象不能被期退直到它被刷新至服务端。 对于瞬态对象（暂不支持） 对象的引脚数递减。瞬态对象只能在其分配持续时间结束时或通过调用显式释放时释放 DCIObjectFree()。 对于值（暂不支持） 此函数返回错误。 4.69 DCIObjectFree 函数原型： sword DCIObjectFree ( DCIEnv *env, DCIError *err, void *instance, ub2 flags ); 功能描述： 释放和取消固定对象实例。 参数说明： 88 第 4 章 DCI 函数 • env(输入/输出) 以对象模式初始化的 DCI 环境句柄。 • err(输入/输出) DCI 错误句柄。出错时错误记录在 err 中，通过调用 DCIErrorGet() 获取诊断信息。 • instance(输入) 指向独立实例的指针。如果是对象，则必须是已固定对象。 • cflgp(输入/输出) 如果传入值为 DCI_OBJECTFREE_FORCE，则释放该对象，即使它已被固定或已标记为 dirty。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 此函数释放为对象实例分配的所有内存，包括 NULL 结构。以下规则适用于不同的实例类型： 对于持久对象 如果客户端尝试释放尚未刷新的 dirty 持久对象，此函数将返回错误。客户端调用该函数前应先刷新持久 对象、取消标记，或者将参数 flags 直接设置为 DCI_OBJECTFREE_FORCE。 该函数会隐式调用一次 DCIObjectUnpin() 以检查对象是否可以完全取消固定。如果成功，函数将继续进 行释放对象的操作。如果失败，则返回错误，除非参数 flags 设置为 DCI_OBJECTFREE_FORCE。 释放内存中的持久对象不会更改该对象在服务器上的持久状态。例如，对象在释放后仍保持锁定状态。 对于瞬态对象 (暂不支持) 该函数会隐式调用一次 DCIObjectUnpin() 以检查对象是否可以完全取消固定。如果成功，函数将继续进 行释放对象的操作。如果失败，则返回错误，除非参数 flags 设置为 DCI_OBJECTFREE_FORCE。 对于值 (暂不支持) 对象的内存被立即释放。 4.70 DCIBindObject 函数原型： sword DCIBindObject ( DCIBind *bindp, DCIError *errhp, const DCIType *type, void **pgvpp, ub4 *pvszsp, 89 第 4 章 DCI 函数 void **indpp, ub4 *indszp, ); 功能描述： 设置命名数据类型（对象）绑定所需的附加属性。 参数说明： • bindp(输入) DCIBind 类接口返回的绑定句柄。 • errhp(输入/输出) DCI 错误句柄。出错时错误记录在 errhp 中，通过调用 DCIErrorGet() 获取诊断信息。 • type(输入) 指向描述被绑定的程序变量的类型的 TDO。通过调用 DCITypeByName() 检索得到。绑定 SQL 中的 REFs 时 该参数是可选的，但绑定 PL/SQL 中的 REFs 时则是必传的。 • pgvpp(输入/输出) 程序变量缓冲区的地址。 • pvszsp(输入/输出) 指向程序变量的大小。输入时不需要指定数据类型的大小。 • indpp(输入/输出) 包含并行指示器结构的程序变量缓冲区地址。 • indszp(输入/输出) 指向 IN“指示器结构体变量”的大小。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 该函数用于设置命名数据类型或 REF 的绑定信息。如果在非对象模式下初始化 DCI 环境并调用此函数，则会返 回错误。 该调用将数据类型 DCIType 的类型描述符对象 (TDO) 作为参数，用于已定义的命名数据类型。 不再使用客户端库所分配的缓冲区内存时，须通过 DCIObjectFree() 调用来释放。 4.71 DCIDefineObject 函数原型： 90 第 4 章 DCI 函数 sword DCIDefineObject ( DCIDefine *defnp, DCIError *errhp, const DCIType *type, void **pgvpp, ub4 *pvszsp, void **indpp, ub4 *indszp ); 功能描述： 设置命名数据类型或 REF 定义所需的附加属性。 参数说明： • defnp(输入) 调用该函数取前在调用 DCIDefineByPos() 或 DCIDefineByPos2() 时分配的定义句柄。 • errhp(输入/输出) DCI 错误句柄。出错时错误记录在 errhp 中，通过调用 DCIErrorGet() 获取诊断信息。 • type(输入) 指向描述程序变量类型的类型描述符对象 (TDO)。该参数对于类型为 SQLT_REF 的变量是可选的，并且在没 有使用该参数时可以传入 NULL。 • pgvpp(输入) 指向程序变量缓冲区的指针。在提取结束并接收到所有值时，pgvpp 指向这些新分配的命名数据类型实例的指 针。当不再需要这些命名数据类型实例时，应用程序必须调用 DCIObjectFree() 以释放它们。 • pvszsp(输入/输出) 指向程序变量的大小。 • indpp(输入/输出) 指向包含了并行指示器结构的程序变量缓冲区的指针。在对象缓存中分配内存以存储指示器结构。在提取结束 并接收到所有值时，indpp 指向这些新分配的指示器结构的指针。 • indszp(输入/输出) 指向指示器结构程序变量的大小。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 该函数在调用 DCIDefineByPos() 或 DCIDefineByPos2() 设置初始定义信息之后调用。它将设置命名数据类型定 义所需的附加属性。如果在非对象模式下初始化的 DCI 环境中调用此函数，则会返回错误。 该调用将数据类型 DCIType 的类型描述符对象 (TDO) 作为参数，用于已定义的命名数据类型。 91 第 4 章 DCI 函数 4.72 DCIStringAssignText 函数原型： sword DCIStringAssignText ( DCIEnv *env, DCIError *err, const OraText *rhs, ub4 rhs_len, DCIString **lhs ); 功能描述： 将源字符串赋值给目的字符串。 参数说明： • env(输入) 以对象模式初始化的 DCI 环境句柄。 • err(输入/输出) DCI 错误句柄。出错时错误记录在 err 中，通过调用 DCIErrorGet() 获取诊断信息。 • rhs(输入) 赋值操作的右值，文本字符串或 UTF-16 字符串。 （UTF-16 编码格式暂不支持） • rhs_len(输入) 右值 rhs 的长度。 • lhs(输入/输出) 赋值操作的左 (目标) 值，如果 rhs 变量为 Unicode 编码则该变量也为 Unicode 编码。 （UTF-16 编码格式暂不支持） 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 将 rhs 字符创赋值给 lhs 字符串。lhs 会根据 rhs 的长度重新分配内存。被赋值的字符串会以 NULL 结尾。长度 域不包含字符结束符所占用的额外字节。 4.73 DCIStringPtr 函数原型： 92 第 4 章 DCI 函数 sword DCIStringPtr ( DCIEnv const DCIString *env, *vs ); 功能描述： 返回给定 DCIString 字符串的文本内容指针。 参数说明： • env(输入) 以对象模式初始化的 DCI 环境句柄。 • vs(输入) 待返回的字符串所在的 DCIString 对象指针。如果 vs 参数传入的是 UTF-16 编码的对象，则返回的缓存同样为 UTF-16 编码。该函数将自行检测 DCISting 对象 vs 的 UTF-16 信息，以确定返回的缓存的编码格式，因为不 能确保一个普通的 DCIString 同 env 具有相同的编码格式设置。 DCI 对象检查函数设计的是检查 DCI 对象的成员域。 （UTF-16 编码格式暂不支持） 返回值： 如果执行成功，返回文本指针，否则返回空。 4.74 DCIDirPathPrepare 函数原型： sword DCIDirPathPrepare(DCIDirPathCtx *dpctx, DCISvcCtx *svchp, DCIError *errhp) 功能描述： 准备直接文件操作。在执行文件函数之前，文件操作的信息都要在文件操作环境的上下文件属性中预先设置好。 参数说明： • dpctx(输入) 文件操作环境。 • svchp(输入) 执行所用的上下文句柄。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 93 第 4 章 DCI 函数 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 注释： 在调用该函数之前，先要在 dpctx 上下文件中设置好要操作的表信息。 4.75 DCIDirPathColArrayEntrySet 函数原型： sword DCIDirPathColArrayEntrySet(DCIDirPathColArray *dpca, DCIError *errhp, ub4 rownum, ub2 colIdx, ub1 *cvalp, ub4 clen, ub1 cflg) 功能描述： 设置写入文件数据数组上指定位置的数据内容。 参数说明： • dpca(输入) 数据数组描述符指针。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • rownum(输入) 设置的数据内容在数组中的行号。 • colIdx(输入) 设置的数据内容在数组中的列号。 • cvalp(输入) 设置的数据内容缓冲区指针。 • clen(输入) 数据内容的长度。 • cflg(输入) 数据属性标识，支持以下几种标识： 94 第 4 章 DCI 函数 – DCI_DIRPATH_COL_COMPLETE 在分批设置数据时，使用该标识表示数据已经结束 – DCI_DIRPATH_COL_NULL 表示设置的数据是一个空 (NULL) – DCI_DIRPATH_COL_PARTIAL 分批设置数据，表示当前设置的数据只是一部分 – DCI_DIRPATH_COL_ERROR 错误的数据，会在该位置用空来替代 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.76 DCIDirPathColArrayToStream 函数原型： sword DCIDirPathColArrayToStream(DCIDirPathColArray *dpca, DCIDirPathCtx *dpctx, DCIDirPathStream *dpstr, DCIError *errhp, ub4 rowcnt, ub4 rowoff) 功能描述： 把数据数组转换成为数据流。如果数组中存在不合法的数据，函数会执行失败，目前还没有实现定位错误数据的 位置功能。 参数说明： • dpca(输入) 数据数组描述符指针。 • dpstr(输入) 数据流描述符指针。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • rowcnt(输入) 要转换的行数。 • rowoff(输入) 转换时在原数组上的起始偏移行号。 返回值： 95 第 4 章 DCI 函数 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR，如果启用了分批传送，那么在需要数据的情况 下会返回 DCI_NEED_DATA，表示分批设置数据还未完成，需要继续设置数据。 4.77 DCIDirPathLoadStream 函数原型： sword DCIDirPathLoadStream(DCIDirPathCtx *dpctx, DCIDirPathStream *dpstr, DCIError *errhp) 功能描述： 写入转换后的数据流到文件。 参数说明： • dpctx(输入) 文件操作环境。 • dpstr(输入) 数据流描述符指针。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.78 DCIDirPathDataSave 函数原型： sword DCIDirPathDataSave(DCIDirPathCtx *dpctx, DCIError *errhp, ub4 action) 功能描述： 保存转换成功的数据流到文件 参数说明： 96 第 4 章 DCI 函数 • dpctx(输入) 文件操作环境。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • action(输入) 保留参数，还未单独处理。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.79 DCIDirPathColArrayReset 函数原型： sword DCIDirPathColArrayReset(DCIDirPathColArray DCIError *dpca, *errhp) 功能描述： 重置数据数组，以便再次重新设置新的内容。 参数说明： • dpca(输入) 数据数组描述符指针。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.80 DCIDirPathStreamReset 函数原型： sword DCIDirPathStreamReset(DCIDirPathStream DCIError *dpstr, *errhp) 97 第 4 章 DCI 函数 功能描述： 重置数据流句柄，清空以前的转换设置。 参数说明： • dpstr(输入) 数据流描述符指针。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.81 DCIDirPathFinish 函数原型： sword DCIDirPathFinish(DCIDirPathCtx DCIError *dpctx, *errhp) 功能描述： 完成直接文件操作，清空相应的环境。 参数说明： • dpctx(输入) 文件操作环境。 • malocfp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.82 DCIDirPathFlushRow 函数原型： sword DCIDirPathFlushRow(DCIDirPathCtx DCIError *dpctx, *errhp) 98 第 4 章 DCI 函数 功能描述： 提交部分数据到数据库。 参数说明： • dpctx(输入) 文件操作环境。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.83 DCIErrorGet 函数原型： sword DCIErrorGet(dvoid *hndlp, ub4 recordno, DciText *sqlstate, sb4 *errcodep, DciText *bufp, ub4 bufsiz, ub4 type) 功能描述： 获取 DCI 操作失败产生的错误信息。 参数说明： • hndlp(输入) 错误信息句柄指针。 • recordno(输入) 错误信息位置，目前只支持一条错误信息，所以请把该参数置为 1。 • sqlstate(输出) 错误的状态码。 • errcodep(输出) 错误码，目前定义了以下几种错误码： – 1 –违反唯一性约速 99 第 4 章 DCI 函数 – 1014 –服务器连接已经关闭 – 1092 –连接异常中止 – 1653 –表空间不足 – 604 –表不存在 • bufp(输出) 错误的描述信息。 • bufsiz(输入) bufp 所指的缓冲区大小。 • type 仅支持 DCI_HTYPE_ERROR 和 DCI_HTYPE_ENV 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.84 DCIDateTimeConstruct 函数原型： sword DCIDateTimeConstruct(void *hndl, DCIError *err, DCIDateTime *datetime, sb2 year, ub1 month, ub1 day, ub1 hour, ub1 min, ub1 sec, ub4 fsec, DciText *timezone， size_t timezone_length) 功能描述： 初始化 datetime 描述符的信息。 参数说明： • hndl(输入) Session 句柄 (或 Env 句柄) 100 第 4 章 DCI 函数 • err(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • datetime(输入) DCIDateTime 的描述符指针。 • year(输入) 年。 • month(输入) 月。 • day(输入) 日。 • hour(输入) 时。 • min(输入) 分。 • sec(输入) 秒。 • fsec(输入) 微秒。 • timezone 时区，若没有设置时区，则默认 session 中的时区。 • timezone_length 时区的字符长度。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.85 DCIDateTimeGetDate 函数原型： sword DCIDateTimeGetDate(void *hndl, DCIError *err, const DCIDateTime *datetime, 101 第 4 章 DCI 函数 sb2 *year, ub1 *month, ub1 *day) 功能描述： 获取 DCIDateTime 中的日期信息。 参数说明： • hndl(输入) Session 句柄 (或 Env 句柄)。 • err(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • datetime(输入) 要获取的 DCIDateTime 描述符指针。 • year(输出) 返回的年。 • month(输出) 返回的月。 • day(输出) 返回的日。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.86 DCIDateTimeGetTime 函数原型： sword DCIDateTimeGetTime(void *hndl, DCIError *err, const DCIDateTime *datetime, ub1 *hour, ub1 *min, ub1 *sec, ub4 *fsec) 102 第 4 章 DCI 函数 功能描述： 获取 DCIDateTime 中的时间信息。 参数说明： • hndl(输入) Session 句柄 (或 Env 句柄)。 • err(输入) 误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • datetime(输入) 要获取的 DCIDateTime 描述符指针。 • hour(输出) 返回的时。 • min(输出) 返回的分。 • sec(输出) 返回的秒。 • fsec(输出) 返回的微秒。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.87 DCIIntervalGetDaySecond 函数原型： sword DCIIntervalGetDaySecond(void *hndl, DCIError *err, sb4 *dy, sb4 *hr, ub1 *mm, sb4 *ss, ub4 *fsec, const DCIInterval *interval) 功能描述： 103 第 4 章 DCI 函数 获取 DCIInterval 中的时间信息。 参数说明： • hndl(输入) Session 句柄 (或 Env 句柄)。 • err(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • dy(输出) 返回的日。 • hr(输出) 返回的时。 • mm(输出) 返回的分。 • ss(输出) 返回的秒。 • fsec(输出) 返回的微秒。 • interval(输入) DCIInterval 描述符指针。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.88 DCIIntervalGetYearMonth 函数原型： sword DCIIntervalGetYearMonth(void *hndl, DCIError *err, sb4 *yr, sb4 *mnth, const DCIInterval *interval) 功能描述： 获取 DCIInterval 中的日期信息 (年月)。 104 第 4 章 DCI 函数 参数说明： • hndl(输入) Session 句柄 (或 Env 句柄)。 • err(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • yr(输出) 返回的年。 • mnth(输出) 返回的月。 • interval(输入) DCIInterval 描述符指针。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.89 DCIIntervalFromText 函数原型： sword DCIIntervalFromText(void *hndl, DCIError *err, const DciText *inpstring, size_t str_len, const DCIInterval *result) 功能描述： 从字符串形式转到 DCIInterval。 参数说明： • hndl(输入) Session 句柄 (或 Env 句柄)。 • err(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • inpstring(输入) 输入的字符串形式的 interval: 105 第 4 章 DCI 函数 – year(-4713 to 9999) – month(1 to 12) – day(1 to 28...31) – hour(0 to 23) – hour(0 to 11)(am, pm) – minutes(0 to 59) – seconds(0 to 59) – The seconds in the day(0 to 86399) • str_len(输入) 输入字符串的长度。 • result(输出) 存储解析 interval 信息后的 DCIInterval 指针。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.90 DCIIntervalAssign 函数原型： sword DCIIntervalAssign(void *hndl, DCIError *err, const DCIInterval *inpinter, DCIInterval *outinter) 功能描述： 通过字符串构造 DCIInterval。 参数说明： • hndl(输入) Session 句柄 (或 Env 句柄)。 • err(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • inpinter(输入) interval 类型的输入值。 106 第 4 章 DCI 函数 • outinter(输出) interval 类型的输出值。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.91 DCIIntervalSetDaySecond 函数原型： sword DCIIntervalSetDaySecond(void *hndl, DCIError *err, sb4 dy, sb4 hr, sb4 mm, sb4 ss, sb4 fsec, DCIInterval *result) 功能描述： 设置 DCIInterval 中的时间信息。 参数说明： • hndl(输入) Session 句柄 (或 Env 句柄)。 • err(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • dy(输入) 输入的日数。 • hr(输入) 输入的小时数。 • mm(输入) 输入的分钟数。 • ss(输入) 输入的秒数。 • fsec(输入) 107 第 4 章 DCI 函数 输入的微秒。 • result(输出) 用于返回的 DCIInterval 描述符指针。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.92 DCIIntervalSetYearMonth 函数原型： sword DCIIntervalSetYearMonth(void *hndl, DCIError *err, sb4 yr, sb4 mnth, DCIInterval *result) 功能描述： 获取 DCIInterval 中的日期信息 (年月)。 参数说明： • hndl(输入) Session 句柄 (或 Env 句柄)。 • err(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • yr(输入) 输入的年份。 • mnth(输入) 输入的小时数。 • result(输出) 用于返回的 DCIInterval 描述符指针。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 108 第 4 章 DCI 函数 4.93 DCIIntervalAdd 函数原型： sword DCIIntervalAdd(void *hndl, DCIError *err, DCIInterval *addend1, DCIInterval *addend2, DCIInterval *result) 功能描述： 将两个 DCIInterval 类型的值相加得到一个新的 DCIInterval 类型的值。 参数说明： • hndl(输入) Session 句柄 (或 Env 句柄)。 • err(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • addend1(输入) interval 类型的输入值。 • mnth(输入) interval 类型的输入值。 • result(输出) interval 类型的输出值。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.94 DCIIntervalToText 函数原型： sword DCIIntervalToText(void *hndl, DCIError *err, const DCIInterval *interval, ub1 lfprec, ub1 fsprec, DciText *buffer, 109 第 4 章 DCI 函数 size_t buflen, size_t *resultlen ) 功能描述： 将 DCIInterval 类型的值转换成通用字符串。 参数说明： • hndl(输入) Session 句柄 (或 Env 句柄)。 • err(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • interval(输入) 用于转换的 interval 类型的输入值。 • lfprec(输入) 主部精度。 • fsprec(输入) 分部精度。 • buffer(输出) 保存结果值的 buffer。 • buflen(输入) buffer 的长度。 • resultlen(输出) 放入 buffer 中的结果的长度。 返回值： 如果执行成功，返回 DCI_SUCCESS；如果 err 句柄是 NULL 指针，返回 DCI_INVALID_HANDLE；否则在 以下情况下，返回 DCI_ERROR：buffer 长度不足以保存结果时。 4.95 DCINumberToText 函数原型： sword DCINumberToText(DCIError *err, const DCINumber *number, const DciText *fmt, 110 第 4 章 DCI 函数 ub4 fmt_length, const DciText *nls_params, ub4 nls_p_length, ub4 *buf_size, DciText *buf) 功能描述： 将 DCINumber 的值转换成字符串。 参数说明： • err(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • number(输入) 有效的 DCINumber 指针。 • fmt(输入) 转换的格式: – 9 - 带有指定数值位数的十进制值 – 0 - 带前导零的值 – . - （句号）小数点 – , - （逗号）分组（千）分隔符 – PR - 尖括号内负值 – S - 带负号的负值（使用区域设置） – L - 货币符号（使用区域设置） – D - 小数点（使用区域设置） – G - 分组分隔符（使用区域设置） – MI - 在指明的位置的负号（如果数字 < 0） – PL - 在指明的位置的正号（如果数字 > 0） – SG - 在指明的位置的正/负号 – RN - 罗马数字（输入在 1 和 3999 之间） – TH 或 th - 转换成序数 – V - 移动 n 位（小数）（参阅注解） – X - 带有指定数值位数的十六进制值 – EEEE - 科学记数。（现在还不支持） 111 第 4 章 DCI 函数 • fmt_length(输入) fmt 的字节长度。 • nls_params(输入) 保留参数，目前不使用。。 • nls_p_length(输入) 保留参数，目前不使用。。 • buf_size(输出) buf 的字节长度。 • buf(输出) 输出的 DCINumber 的字符形式存储到该指针指向的内存。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.96 DCINumberFromText 函数原型： sword DCINumberFromText(DCIError *err, const DciText *str, ub4 str_length, const DciText *fmt, ub4 fmt_length, const DciText *nls_params, ub4 nls_p_length, DCINumber *number) 功能描述： 从字符串转换成 DCINumber。 参数说明： • err(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • str(输入) 输入的 DCINumber 的字符串形式。 • str_length(输入) 112 第 4 章 DCI 函数 str 的字节长度。 • fmt(输入) 转换的格式，同 DCINumberToText。 • fmt_length(输入) fmt 的字节长度。 • nls_params(输入) 保留参数，目前不使用。 • nls_p_length(输入) 保留参数，目前不使用。 • number(输出) 输出的 DCINumber 指针。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.97 DCINumberToInt 函数原型： sword DCINumberToInt(DCIError *err, const DCINumber *number, uword rsl_length, uword rsl_flag, void *rsl) 功能描述： 将 DCINumber 的值转换成整型数值。 参数说明： • err(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • number(输入) 有效的 DCINumber 指针。 • rsl_length(输入) rsl 的字节长度。 113 第 4 章 DCI 函数 • rsl_flag(输入) Sign 标识： – DCI_NUMBER_UNSIGNED – DCI_NUMBER_SIGNED • rsl(输出) 整型指针，DCINumber 的数值形式被写入该指针指向的内存。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.98 DCINumberFromInt 函数原型： sword DCINumberFromInt(DCIError *err, const void *inum, uword inum_length, uword inum_s_flag, DCINumber *number) 功能描述： 将整型的数值转换成 DCINumber。 参数说明： • err(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • inum(输入) 指向整型数值的指针。 • inum_length(输入) 整型数值的长度。 • inum_s_flag(输入) Sign 标识： – DCI_NUMBER_UNSIGNED – DCI_NUMBER_SIGNED 114 第 4 章 DCI 函数 • number(输出) 有效的 DCINumber 指针，将 inum 指向的值写入 DCINumber。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.99 DCINumberToReal 函数原型： sword DCINumberToReal(DCIError *err, const DCINumber *number, uword rsl_length, void *rsl) 功能描述： 将 DCINumber 的值转换成浮点型的数值。 参数说明： • err(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • number(输入) 有效的 DCINumber 指针。 • rsl_length(输入) rsl 的字节长度。 • rsl(输出) 浮点型类型指针，DCINumber 的数值形式被写入该指针指向的内存。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.100 DCINumberFromReal 函数原型： 115 第 4 章 DCI 函数 sword DCINumberFromReal(DCIError *err, const void *rnum, uword rnum_length, DCINumber *number) 功能描述： 将浮点型的数值转换成 DCINumber 的值。 参数说明： • err(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • rnum(输入) 有效的指向浮点类型的指针。 • rnum_length(输入) rnum 的字节长度。 • number(输出) 有效的 DCINumber 指针。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.101 DCIDateGetDate 函数原型： sword DCIDateGetDate(const DCIDate *date, sb2 *year, ub1 *month, ub1 *day ); 功能描述： 获取 DCIDate 中的日期信息 (年月日)。 参数说明： • date(输入) DCIDate 类型的日期值。 • year(输出) 116 第 4 章 DCI 函数 要输出的年份值。 • month(输出) 要输出的月份值。 • day(输出) 要输出的天数值。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.102 DCIDateGetTime 函数原型： sword DCIDateGetTime(const DCIDate *date, sb2 *hour, ub1 *min, ub1 *day ); 功能描述： 获取 DCIDate 中的时间信息 (时分秒)。 参数说明： • date(输入) DCIDate 类型的日期值。 • hour(输出) 要输出的小时值。 • min(输出) 要输出的分钟值。 • sec(输出) 要输出的秒值。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 117 第 4 章 DCI 函数 4.103 DCIDateSetDate 函数原型： sword DCIDateSetDate( DCIDate *date, sb2 *year, ub1 *month, ub1 *day ); 功能描述： 设置 DCIDate 中的日期信息 (年月日)。 参数说明： • date(输出) 需要设置的 DCIDate 类型的日期值。 • year(输入) 要设置的年份值。 • month(输入) 要设置的月份值。 • day(输入) 要设置的天数值。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.104 DCIDateSetTime 函数原型： sword DCIDateSetTime( DCIDate *date, sb2 *hour, ub1 *min, ub1 *day ); 功能描述： 设置 DCIDate 中的时间信息 (时分秒)。 参数说明： 118 第 4 章 DCI 函数 • date(输出) 要设置的 DCIDate 类型的日期值。 • hour(输入) 要设置的小时值。 • min(输入) 要设置的分钟值。 • sec(输入) 要设置的秒值。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.105 DCIDateSysDate 函数原型： sword DCIDateSysDate( DCIError DCIDate *err, *date); 功能描述： 获取客户端所在的本地的系统日期 (时间)。 参数说明： • err(输入/输出) 用于设置或者获取错误信息的错误句柄。 • sys_date(输出) 要设置的年份值。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.106 DCIDateAssign 函数原型： 119 第 4 章 DCI 函数 sword DCIDateAssign( DCIError *err, const DCIDate *from, DCIDate *to); 功能描述： 将 DCIDate 类型的日期 (时间) 赋值给另一个 DCIDate 类型的值。 参数说明： • err(输入/输出) 用于设置或者获取错误信息的错误句柄。 • from(输入) 赋值日期值的来源。 • to(输出) 要赋值的日期值。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.107 DCIDateTimeSysTimeStamp 函数原型： sword DCIDateTimeSysTimeStamp( void *hndl, DCIError *err, DCIDateTime *sys_date); 功能描述： 获取客户端所在系统的本地带时间戳带时区的系统日期。 参数说明： • hndl(输入) 用户会话句柄或者环境句柄。 • err(输入) 赋值日期值的来源。 • sys_date(输出) 要获取的 DCIDateTime 类型的带时间戳带时区的系统日期值。 120 第 4 章 DCI 函数 返回值： 如果执行成功，返回 DCI_SUCCESS，hndl 句柄或 err 句柄为 NULL 时返回 DCI_INVALID_HANDLE。 4.108 DCIDateTimeAssign 函数原型： sword DCIDateTimeAssign( void *hndl, DCIError *err, const DCIDateTime *from, DCIDateTime *to); 功能描述： 将一个带时间戳带时区的 DCIDateTime 日期值赋值给另外一个 DCIDateTime 类型的日期值。 参数说明： • hndl(输入) 用户会话句柄或者环境句柄。 • err(输入/输出) 用于设置或者获取错误信息的错误句柄。 • from(输入) 赋值日期值的来源。 • to(输出) 要赋值的 DCIDateTime 类型的带时间戳带时区的日期值。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.109 DCIStmtGetPieceInfo 函数原型： sword DCIStmtGetPieceInfo(const DCIStmt *stmtp, DCIError *errhp, void **hndlpp, ub4 *typep, ub1 *in_outp, 121 第 4 章 DCI 函数 ub4 *iterp, ub4 *idxp, ub1 *piecep) 功能描述： 返回分段信息，对于大数据类型进行分段操作时有用。支持的数据类型:BLOB、CLOB、TEXT、BYTEA。 参数说明： • stmtp(输入) 语句句柄。 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • hndlpp(输出) 返回的句柄类型： – DCI_HTYPE_BIND - Bind 类型 – DCI_HTYPE_DEFINE - Define 类型 • in_outp(输出) 输入输出类型： – DCI_PARAM_IN - 输入类型 (Bind 参数) – DCI_PARAM_OUT - 输出类型 (Define 的结果集) • iterp(输出) 多行处理的行号。 • idxp(输出) 数组绑定的索引号。 • piecep(输出) 分段操作的类型： – DCI_ONE_PIECE - 只需要一次 – DCI_FIRST_PIECE - 多次中的第一次 – DCI_NEXT_PIECE - 多次中的下一次 – DCI_LAST_PIECE - 多次中的最后一次 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 122 第 4 章 DCI 函数 4.110 DCIStmtSetPieceInfo 函数原型： sword DCIStmtSetPieceInfo(void *hndlp, ub4 type, DCIError *errhp, const void *bufp, ub4 *alenp, ub1 piece, const void *indp, ub2 *rcodep) 功能描述： 设置分段信息，对于大数据类型进行分段操作时有用。支持的数据类型:BLOB、CLOB、TEXT、BYTEA。 参数说明： • hndlp(输入) 有效的 Bind 或者 Define 句柄。 • type(输入) hndlp 的句柄类型： – DCI_HTYPE_BIND - Bind 类型 – DCI_HTYPE_DEFINE - Define 类型 • errhp(输入) 错误信息句柄，该接口调用失败时，错误信息会存在该句柄上。 • bufp(输入) 分段操作的数据指针。 • alenp(输入) 本次分段处理的数据长度。 • piece(输入) 分段处理的类型： – DCI_ONE_PIECE - 只需要一次 – DCI_FIRST_PIECE - 多次中的第一次 – DCI_NEXT_PIECE - 多次中的下一次 – DCI_LAST_PIECE - 多次中的最后一次 123 第 4 章 DCI 函数 • indp(输出) Indicator 类型，可以是数组类型。 • rcodep(输出) 返回代码，可以是数组指针。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 4.111 DCIDurationBegin 函数原型： sword DCIDurationBegin (DCIEnv *env, DCIError *err, const DCISvcCtx *svc, DCIDuration parent, DCIDuration *duration ); 功能描述： 开始用户的持续时间。 参数说明： • env(输入) 用户会话句柄或者环境句柄。 • err(输入/输出) DCI 错误信息句柄，如果函数执行错误会返回 DCI_ERROR，可通过 DCIErrorGet 获取错误信息 • svc(输入) DCI 服务上下文句柄。 • parent(输入) 父持续时间数。取值可以是： 1. 先前创建的用户持续时间数 2. DCI_DURATION_STATEMENT 3. DCI_DURATION_SESSION • duration(输出) 要获取的用户持续时间数的标识。 124 第 4 章 DCI 函数 返回值： 如果执行成功，返回 DCI_SUCCESS。 4.112 DCIDurationEnd 函数原型： sword DCIDurationEnd ( DCIEnv *env, DCIError *err, const DCISvcCtx *svc, DCIDuration *duration ); 功能描述： 结束用户创建的持续时间。 参数说明： • env(输入) 用户会话句柄或者环境句柄。 • err(输入/输出) DCI 错误信息句柄，如果函数执行错误会返回 DCI_ERROR，可通过 DCIErrorGet 获取错误信息 • svc(输入) DCI 服务上下文句柄。 • duration(输入) 用户持续时间数的标识。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。 该函数用于结束用户创建的持续时间，为用户持续时间创建的临时 LOB 对象会同步被释放。 4.113 DCIRowidToChar 函数原型： sword DCIRowidToChar ( DCIRowid *rowidDesc, DciText *outbfp, ub2 *outbflp DCIError *errhp ); 125 第 4 章 DCI 函数 功能描述： 将通用的 Rowid 转换成字符类型的值。 参数说明： • rowidDesc(输入) ROWID 类型的描述符。 • outbfp(输出) 用于保存转换成功后的值的缓存区。 • outbflp(输入/输出) 指向记录保存缓存区的长度变量的指针，执行该函数前变量存放 outbfp 的长度，执行成功后保存转换字符数。 • errhp(输入) 用于设置或者获取错误信息的错误句柄。 返回值： 如果执行成功，返回 DCI_SUCCESS，否则返回 DCI_ERROR。转换后得到的字符格式的 ROWID 值可被 DCIBindByPos() 或 DCIBindByName() 函数用于绑定，以查询其对应的行。 4.114 DCIDateTimeFromText 函数原型： sword DCIDateTimeFromText(void *hndlp, DCIError *errhp, const DciText *date_str, size_t dstr_length, const DciText *fmt, ub1 fmt_length, const DciText *lang_name, size_t lang_length, DCIDateTime *datetime) 功能描述： 把字符串按照一定格式转换成 DateTime 类型 参数说明： • hndlp(输入) DCI 环境句柄 126 第 4 章 DCI 函数 • errhp(输入/输出) DCI 错误信息句柄，如果函数执行错误会返回 DCI_ERROR，可通过 DCIErrorGet 获取错误信息 • date_str(输入) 用来转换的日期字符串 • dstr_length(输入) 日期字符串的长度，指定 date_str 的实际输入长度 • fmt(输入) 日期格式串 • fmt_length(输入) 日期格式串的长度 • lang_name(输入) 日期中语言的名称 • lang_length(输入) 语言字符串的长度 • datetime(输出) DCIDateTime 类型的指针，输入的字符串会转换成该类型 返回值： 如果执行成功，返回 DCI_SUCCESS。 如果句柄为 NULL，或 datetime 为 NULL，或环境句柄类型不正确，则返回 DCI_INVALID_HANDLE。 否则返回 DCI_ERROR。 注释： 默认 lang_name 为 NULL，不处理。 4.115 DCIDateTimeToText 函数原型： sword DCIDateTimeToText(void *hndlp, DCIError *errhp, const DCIDateTime *datetime, const DciText *fmt, ub1 fmt_length, ub1 fsprec, 127 第 4 章 DCI 函数 const DciText *lang_name, size_t lang_length, ub4 *bufsz, DciText *bufp) 功能描述： 根据指定格式把一个日期类型数据转换成字符串 参数说明： • hndlp(输入) DCI 环境句柄 • errhp(输入/输出) DCI 错误信息句柄，如果函数执行错误会返回 DCI_ERROR，可通过 DCIErrorGet 获取错误信息 • datetime(输入) 用来转换的 DCIDatetime 类型指针 • fmt(输入) 日期格式串 • fmt_length(输入) 日期格式串的长度 • fsprec(输入) 指定返回结果的字符串中，毫秒的精度 • lang_name(输入) 日期中语言的名称 • lang_length(输入) 语言字符串的长度 • bufsz(输入/输出) 返回结果字符串的长度，如果转换过程无误，最终结果又比传入长度小，该值会赋值为当前长度的值并返回 • bufp(输出) 缓冲区指针，转换后的字符串存入该区域 返回值： 如果执行成功，返回 DCI_SUCCESS。 如果句柄为 NULL，则返回 DCI_INVALID_HANDLE。 如果缓冲区的大小小于转换后的结果字符串，返回 DCI_ERROR，错误码 1877。 128 第 4 章 DCI 函数 注释： 默认 lang_name 为 NULL，不处理。 4.116 DCIDateFromText 函数原型： sword DCIDateFromText ( DCIError *errhp, const DciText *date_str, size_t d_str_length, const DciText *fmt, ub1 fmt_length, const DciText *lang_name, size_t lang_length, DCIDate *date) 功能描述： 把字符串按照一定格式转换成 Date 类型 参数说明： • errhp(输入/输出) DCI 错误信息句柄，如果函数执行错误会返回 DCI_ERROR，可通过 DCIErrorGet 获取错误信息 • date_str(输入) 用来转换的日期字符串 • dstr_length(输入) 日期字符串的长度，指定 date_str 的实际输入长度 • fmt(输入) 日期格式串 • fmt_length(输入) 日期格式串的长度 • lang_name(输入) 日期中语言的名称 • lang_length(输入) 语言字符串的长度 • date(输出) 129 第 4 章 DCI 函数 DCIDate 类型的指针，输入的字符串会转换成该类型 返回值： 如果执行成功，返回 DCI_SUCCESS。 如果句柄为 NULL，或 datetime 为 NULL，或环境句柄类型不正确，则返回 DCI_INVALID_HANDLE。 否则返回 DCI_ERROR。 注释： 默认 lang_name 为 NULL，不处理。 4.117 DCIDateToText 函数原型： sword DCIDateToText (DCIError *errhp, const DCIDate *date, const DciText *fmt, ub1 fmt_length, const DciText *lang_name, size_t lang_length, ub4 *bufsz, DciText *bufp) 功能描述： 根据指定格式把一个日期类型数据转换成字符串 参数说明： • errhp(输入/输出) DCI 错误信息句柄，如果函数执行错误会返回 DCI_ERROR，可通过 DCIErrorGet 获取错误信息 • date(输入) 用来转换的 DCIDate 类型指针 • fmt(输入) 日期格式串 • fmt_length(输入) 日期格式串的长度 • lang_name(输入) 日期中语言的名称 130 第 4 章 DCI 函数 • lang_length(输入) 语言字符串的长度 • bufsz(输入/输出) 返回结果字符串的长度，如果转换过程无误，最终结果又比传入长度小，该值会赋值为当前长度的值并返回 • bufp(输出) 缓冲区指针，转换后的字符串存入该区域 返回值： 如果执行成功，返回 DCI_SUCCESS。 如果句柄为 NULL，则返回 DCI_INVALID_HANDLE。 如果缓冲区的大小小于转换后的结果字符串，返回 DCI_ERROR，错误码 1877。 注释： 默认 lang_name 为 NULL，不处理。 131 第5章 程序示例 5 第 章 程序示例 • 登录和注销数据库 • 执行一条不返回结果的 SQL 语句 • 执行一条查询语句并获取结果 • 读取大字段数据 • 将数据写入大字段 • DIRPATH 操作 • 批量插入 您可前往 人大金仓官网 下载 DCI 测试用例 。 5.1 登录和注销数据库 #include "dci.h" #include #include#include DCIEnv *envhp; DCIError *errhp; DCISvcCtx *svchp; DCIStmt *stmthp = (DCIStmt *)NULL; sword init_handles(DCIEnv **envhp, DCIError **errhp) { printf("Environment setup ....\n"); 132 第5章 程序示例 if (DCIInitialize(DCI_DEFAULT, (dvoid *)0, (dvoid * (*)(dvoid *, size_t))0, (dvoid * (*)(dvoid *, dvoid *, size_t))0, (void (*)(dvoid *, dvoid *))0)) { printf("FAILED: DCIInitialize()\n"); return DCI_ERROR; } if (DCIEnvInit((DCIEnv **)envhp, (ub4)DCI_DEFAULT, (size_t)0, (dvoid **)0)) { printf("FAILED: DCIEnvInit()\n"); return DCI_ERROR; } if (DCIHandleAlloc((dvoid *)*envhp, (dvoid **)errhp, (ub4)DCI_HTYPE_ERROR, (size_t)0, (dvoid **)0)) { printf("FAILED: DCIHandleAlloc() on errhp\n"); return DCI_ERROR; } return DCI_SUCCESS; } sword log_on(DCIEnv *envhp, DCIError *errhp, text *uid, text *pwd, text *DbName) { printf("Logging on as %s ....\n", uid); if (DCILogon(envhp, errhp, &svchp, uid, (ub4)strlen((char *)uid),pwd, (ub4)strlen((char *)pwd), DbName, (ub4)strlen((char *)DbName))) { printf("FAILED: DCILogon()\n"); return DCI_ERROR; } printf("%s logged on.\n", uid); return DCI_SUCCESS; } 133 第5章 程序示例 sword finish_demo(boolean loggedon, DCIEnv *envhp, DCISvcCtx *svchp, DCIError *errhp, DCIStmt *stmthp) { if (stmthp) DCIHandleFree((dvoid *)stmthp, (ub4)DCI_HTYPE_STMT); printf("logoff ...\n"); if (loggedon) DCILogoff(svchp, errhp); printf("Freeing handles ...\n"); if (svchp) DCIHandleFree((dvoid *)svchp, (ub4)DCI_HTYPE_SVCCTX); if (errhp) DCIHandleFree((dvoid *)errhp, (ub4)DCI_HTYPE_ERROR); if (envhp) DCIHandleFree((dvoid *)envhp, (ub4)DCI_HTYPE_ENV); return DCI_SUCCESS; } void report_error(DCIError *errhp) { text msgbuf[512]; sb4 errcode = 0; DCIErrorGet((dvoid *)errhp, (ub4)1, (text *)NULL, &errcode, msgbuf, (ub4)sizeof(msgbuf), (ub4)DCI_HTYPE_ERROR); printf("ERROR CODE = %d", errcode); printf("%.*s\n", 512, msgbuf); return; } int main() { text *DbName = (text *)"KingbaseES"; text *username = (text *)"SYSTEM"; text *password = (text *)"MANAGER"; int logged_on = FALSE; 134 第5章 程序示例 if (init_handles(&envhp, &errhp) != DCI_SUCCESS) { printf("FAILED: init_handles()\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } if (log_on(envhp, errhp, username, password, DbName) != DCI_SUCCESS) { printf("FAILED: log_on()\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } logged_on = TRUE; return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } 执行一条不返回结果的 SQL 语句 5.2 本示例仅展示主函数的实现, 不再重复展示 init_handles、log_on、finish_demo 和 report_error 等函数，以及 包含的头文件列表。 int main() { text *DbName = (text *)"KingbaseES"; text *username = (text *)"SYSTEM"; text *password = (text *)"MANAGER"; int logged_on = FALSE; char sql[1024]; if (init_handles(&envhp, &errhp)) { printf("FAILED: init_handles()\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } if (log_on(envhp, errhp, username, password, DbName)) { 135 第5章 程序示例 printf("FAILED: log_on()\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } logged_on = TRUE; if (DCIHandleAlloc((dvoid *)envhp, (dvoid **)&stmthp, (ub4)DCI_HTYPE_STMT, (CONST size_t)0, (dvoid **)0)) { printf("FAILED: alloc statement handle\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } strcpy(sql, "CREATE TABLE T(C INT)"); if (DCIStmtPrepare(stmthp, errhp, (unsigned char *)sql, (ub4)strlen((char *)sql), (ub4)DCI_NTV_SYNTAX, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIStmtPrepare() select\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } if (DCIStmtExecute(svchp, stmthp, errhp, (ub4)1, (ub4)0, (CONST DCISnapshot *)0, (DCISnapshot *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIStmtExecute() select\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } 5.3 执行一条查询语句并获取结果 本示例仅展示主函数的实现, 不再重复展示 init_handles、log_on、finish_demo 和 report_error 等函数，以及 包含的头文件列表。 /* 以列绑定的形式来获取数据，每一列的值都连续的存放在一起。 * rows 参数表示每次获取的数据行数 * 假定表 T 的结构为 * T(C1 INT, C2 REAL, C3 CHAR(100 BYTE), C4 VARCHAR(100 BYTE), 136 第5章 * 程序示例 C5 FLOAT, C6 NUMERIC(22,7), C7 TIME) */ #define CHAR_SIZE 101 sword Select_ColumnBind(ub2 rows) { text *sqlstmt = (text *)"select C1, C2, C3, C4, C5, C6, C7 from T"; int *c1 = (int *)malloc(sizeof(int) * rows); float *c2 = (float *)malloc(sizeof(float) * rows); DCIDate *c7 = (DCIDate *)malloc(sizeof(DCIDate) * rows); char *c3 = (char *)malloc(sizeof(char) * rows * CHAR_SIZE); char *c4 = (char *)malloc(sizeof(char) * rows * CHAR_SIZE); float *c5 = (float *)malloc(sizeof(float) * rows); DCINumber *c6 = (DCINumber *)malloc(sizeof(DCINumber) * rows); DCIDefine *bndhp[7]; ub4 stmrow, stmrowEx; if (DCIStmtPrepare(stmthp, errhp, sqlstmt, (ub4)strlen((char *)sqlstmt), (ub4)DCI_NTV_SYNTAX, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIStmtPrepare() select\n"); report_error(errhp); return DCI_ERROR; } memset(c1, 0, sizeof(int) * rows); memset(c2, 0, sizeof(int) * rows); memset(c3, 0, rows * CHAR_SIZE); memset(c4, 0, rows * CHAR_SIZE); memset(c5, 0, sizeof(float) * rows); memset(c6, 0, sizeof(DCINumber) * rows); memset(c7, 0, sizeof(DCIDate) * rows); if (DCIDefineByPos(stmthp, &bndhp[0], errhp, 1, (dvoid *)c1, (sb4)sizeof(int), (ub2)SQLT_INT, (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIDefineByPos()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineByPos(stmthp, &bndhp[1], errhp, 2, (dvoid *)c2, (sb4)sizeof(float), (ub2)SQLT_FLT, (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)DCI_DEFAULT)) 137 第5章 程序示例 { printf("FAILED: DCIDefineByPos()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineByPos(stmthp, &bndhp[2], errhp, 3, (dvoid *)c3, (sb4)CHAR_SIZE, (ub2)SQLT_CHR, (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIDefineByPos()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineByPos(stmthp, &bndhp[3], errhp, 4, (dvoid *)c4, (sb4)CHAR_SIZE, (ub2)SQLT_STR, (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIDefineByPos()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineByPos(stmthp, &bndhp[4], errhp, 5, (dvoid *)c5, (sb4)sizeof(float), (ub2)SQLT_FLT, (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIDefineByPos()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineByPos(stmthp, &bndhp[5], errhp, 6, (dvoid *)c6, (sb4)sizeof(DCINumber), (ub2)SQLT_VNU, (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIDefineByPos()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineByPos(stmthp, &bndhp[6], errhp, 7, (dvoid *)c7, (sb4)sizeof(DCIDate), (ub2)SQLT_ODT, (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIDefineByPos()\n"); report_error(errhp); return DCI_ERROR; } 138 第5章 程序示例 if (DCIDefineArrayOfStruct(bndhp[0], errhp, sizeof(int), 0, 0, 0)) { printf("FAILED: DCIDefineArrayOfStruct()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineArrayOfStruct(bndhp[1], errhp, sizeof(float), 0, 0, 0)) { printf("FAILED: DCIDefineArrayOfStruct()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineArrayOfStruct(bndhp[2], errhp, CHAR_SIZE, 0, 0, 0)) { printf("FAILED: DCIDefineArrayOfStruct()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineArrayOfStruct(bndhp[3], errhp, CHAR_SIZE, 0, 0, 0)) { printf("FAILED: DCIDefineArrayOfStruct()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineArrayOfStruct(bndhp[4], errhp, sizeof(float), 0, 0, 0)) { printf("FAILED: DCIDefineArrayOfStruct()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineArrayOfStruct(bndhp[5], errhp, sizeof(DCINumber), 0, 0, 0)) { printf("FAILED: DCIDefineArrayOfStruct()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineArrayOfStruct(bndhp[6], errhp, sizeof(DCIDate), 0, 0, 0)) 139 第5章 程序示例 { printf("FAILED: DCIDefineArrayOfStruct()\n"); report_error(errhp); return DCI_ERROR; } if (DCIStmtExecute(svchp, stmthp, errhp, (ub4)0, (ub4)0, (CONST DCISnapshot *)0, (DCISnapshot *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIStmtExecute() select\n"); report_error(errhp); return DCI_ERROR; } stmrowEx = 0; while (1) { if (DCIStmtFetch(stmthp, errhp, rows, DCI_FETCH_NEXT, 0) == DCI_ERROR) break; DCIAttrGet(stmthp, DCI_HTYPE_STMT, &stmrow, 0, DCI_ATTR_ROW_COUNT, errhp); if (stmrow == stmrowEx) break; printf(" 提取到了%d 行记录\n", stmrow - stmrowEx); for (int i = 0; i < rows; i++) { printf("************* 第%d 行 ****************\n", i + 1); printf("c1: %d,\t c2:%f\n", c1[i], c2[i]); printf("c3: %s\n", c3 + CHAR_SIZE * i); printf("c4: %s\n", c4 + CHAR_SIZE * i); char c6fmt[] = "999999999999999999999.9999999"; char c6str[255]; int outlen; DCINumberToText(errhp, &c6[i], (DciText *)c6fmt, (ub4)strlen(c6fmt), NULL, 0, (ub4 *)&outlen, (DciText *)c6str); c6str[outlen] = 0; printf("c5: %f,\t c6:%s\n", c5[i], c6str); printf("c7: %d-%d-%d %d:%d:%d\n", (int)c7[i].DCIDateYYYY, c7[i].DCIDateMM, c7[i].DCIDateDD, c7[i].DCIDateTime.DCITimeHH, c7[i].DCIDateTime.DCITimeMI, c7[i].DCIDateTime.DCITimeSS); 140 第5章 程序示例 } stmrowEx = stmrow; } if (DCITransCommit(svchp, errhp, (ub4)DCI_DEFAULT)) { printf("FAILED: DCITransCommit() select\n"); report_error(errhp); return DCI_ERROR; } free(c1); free(c2); free(c3); free(c4); free(c5); free(c6); free(c7); return DCI_SUCCESS; } /* 采用整行绑定的方式来获取记录，值的存放类似自然表格的形式 * rows 参数表示每次获取的数据行数 * 假定表 T 的结构为 * T(C1 INT, C2 REAL, C3 CHAR(100 BYTE), C4 VARCHAR(100 BYTE), * C5 FLOAT, C6 NUMERIC(22,7), C7 DATETIME) */ sword Select_RowBind(ub2 rows) { text *sqlstmt = (text *)"select C1, C2, C3, C4, C5, C6, C7 from T"; char *p; DCIDefine *bndhp[7]; int *c1; float *c2; char *c3; char *c4; float *c5; DCINumber *c6; DCIDate *c7; ub4 stmrow, stmrowEx; int row_size = sizeof(int) + sizeof(float) + sizeof(DCIDate) + CHAR_SIZE + CHAR_SIZE + sizeof(DCINumber) + sizeof(float); 141 第5章 程序示例 p = (char *)malloc(sizeof(char) * row_size * rows); memset(p, 0, row_size * rows); if (DCIStmtPrepare(stmthp, errhp, sqlstmt, (ub4)strlen((char *)sqlstmt), (ub4)DCI_NTV_SYNTAX, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIStmtPrepare() select\n"); report_error(errhp); return DCI_ERROR; } c1 = (int *)p; c2 = (float *)((char *)c1 + sizeof(int)); c3 = ((char *)c2 + sizeof(float)); c4 = (char *)c3 + CHAR_SIZE; c5 = (float *)((char *)c4 + CHAR_SIZE); c6 = (DCINumber *)((char *)c5 + sizeof(float)); c7 = (DCIDate *)((char *)c6 + sizeof(DCINumber)); if (DCIDefineByPos(stmthp, &bndhp[0], errhp, 1, (dvoid *)c1, (sb4)4, (ub2)SQLT_INT, (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIDefineByPos()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineByPos(stmthp, &bndhp[1], errhp, 2, (dvoid *)c2, (sb4)4, (ub2)SQLT_FLT, (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIDefineByPos()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineByPos(stmthp, &bndhp[2], errhp, 3, (dvoid *)c3, (sb4)CHAR_SIZE, (ub2)SQLT_CHR, (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIDefineByPos()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineByPos(stmthp, &bndhp[3], errhp, 4, (dvoid *)c4, (sb4)CHAR_SIZE, (ub2)SQLT_STR, 142 第5章 程序示例 (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIDefineByPos()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineByPos(stmthp, &bndhp[4], errhp, 5, (dvoid *)c5, (sb4)4, (ub2)SQLT_FLT, (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIDefineByPos()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineByPos(stmthp, &bndhp[5], errhp, 6, (dvoid *)c6, (sb4)4, (ub2)SQLT_VNU, (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIDefineByPos()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineByPos(stmthp, &bndhp[6], errhp, 7, (dvoid *)c7, (sb4)sizeof(DCIDate), (ub2)SQLT_ODT, (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIDefineByPos()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineArrayOfStruct(bndhp[0], errhp, row_size, 0, 0, 0)) { printf("FAILED: DCIDefineArrayOfStruct()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineArrayOfStruct(bndhp[1], errhp, row_size, 0, 0, 0)) { printf("FAILED: DCIDefineArrayOfStruct()\n"); report_error(errhp); return DCI_ERROR; } 143 第5章 程序示例 if (DCIDefineArrayOfStruct(bndhp[2], errhp, row_size, 0, 0, 0)) { printf("FAILED: DCIDefineArrayOfStruct()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineArrayOfStruct(bndhp[3], errhp, row_size, 0, 0, 0)) { printf("FAILED: DCIDefineArrayOfStruct()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineArrayOfStruct(bndhp[4], errhp, row_size, 0, 0, 0)) { printf("FAILED: DCIDefineArrayOfStruct()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineArrayOfStruct(bndhp[5], errhp, row_size, 0, 0, 0)) { printf("FAILED: DCIDefineArrayOfStruct()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineArrayOfStruct(bndhp[6], errhp, row_size, 0, 0, 0)) { printf("FAILED: DCIDefineArrayOfStruct()\n"); report_error(errhp); return DCI_ERROR; } if (DCIStmtExecute(svchp, stmthp, errhp, (ub4)0, (ub4)0, (CONST DCISnapshot *)0, (DCISnapshot *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIStmtExecute() select\n"); report_error(errhp); return DCI_ERROR; } 144 第5章 程序示例 stmrowEx = 0; while (1) { if (DCIStmtFetch(stmthp, errhp, rows, DCI_FETCH_NEXT, 0) == DCI_ERROR) break; DCIAttrGet(stmthp, DCI_HTYPE_STMT, &stmrow, 0, DCI_ATTR_ROW_COUNT, errhp); if (stmrow == stmrowEx) break; printf(" 提取到了%d 行记录\n", stmrow - stmrowEx); for (int i = 0; i < rows; i++) { int *c1tmp = (int *)((char *)c1 + i * row_size); float *c2tmp = (float *)((char *)c2 + i * row_size); char *c3tmp = c3 + i * row_size, *c4tmp = c4 + i * row_size; float *c5tmp = (float *)((char *)c5 + i * row_size); DCINumber *c6tmp = (DCINumber *)((char *)c6 + i * row_size); DCIDate *c7tmp = (DCIDate *)((char *)c7 + i * row_size); printf("************* 第%d 行 ****************\n", i + 1); printf("c1: %d,\t c2:%f\n", *c1tmp, *c2tmp); printf("c3: %s\n", c3tmp); printf("c4: %s\n", c4tmp); char c6fmt[] = "999999999999999999999.9999999"; char c6str[255]; int outlen; DCINumberToText(errhp, c6tmp, (DciText *)c6fmt, (ub4)strlen(c6fmt), NULL, 0, (ub4 *)&outlen, (DciText *)c6str); c6str[outlen] = 0; printf("c5: %f,\t c6:%s\n", *c5tmp, c6str); printf("c7: %d-%d-%d %d:%d:%d\n", c7tmp->DCIDateYYYY, c7tmp->DCIDateMM, c7tmp->DCIDateDD,c7tmp->DCIDateTime.DCITimeHH, c7tmp->DCIDateTime.DCITimeMI,c7tmp->DCIDateTime.DCITimeSS); } stmrowEx = stmrow; } if (DCITransCommit(svchp, errhp, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIStmtExecute() select\n"); report_error(errhp); 145 第5章 程序示例 return DCI_ERROR; } free(p); return DCI_SUCCESS; } int main() { text *DbName = (text *)"KingbaseES"; text *username = (text *)"SYSTEM"; text *password = (text *)"MANAGER"; int logged_on = FALSE; if (init_handles(&envhp, &errhp)) { printf("FAILED: init_handles()\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } if (log_on(envhp, errhp, username, password, DbName)) { printf("FAILED: log_on()\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } logged_on = TRUE; if (DCIHandleAlloc((dvoid *)envhp, (dvoid **)&stmthp, (ub4)DCI_HTYPE_STMT, (CONST size_t)0, (dvoid **)0)) { printf("FAILED: alloc statement handle\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } Select_ColumnBind(100); Select_RowBind(100); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } 146 第5章 5.4 程序示例 读取大字段数据 本示例仅展示主函数的实现, 不再重复展示 init_handles、log_on、finish_demo 和 report_error 等函数，以及 包含的头文件列表。 #define COMMENT(x) (void)fprintf(stdout, "\nCOMMENT: %s\n", x) void Read_from_loc(DCISvcCtx *svchp, DCIError *errhp, DCILobLocator *lobp) { ub1 *buf; ub4 readsize = 0; ub4 amtp; ub4 lenp = 0; sb4 err; COMMENT("Read from the locator."); if (DCILobGetLength(svchp, errhp, lobp, &lenp) != DCI_SUCCESS) { COMMENT("Read_from_loc: DCILobGetLength"); return; } else { printf(" Length of Locator is %d\n", lenp); buf = (ub1 *)malloc(sizeof(ub1) * (lenp + 1)); buf[lenp] = '\0'; } printf("\n--------------------------------------------------------------\n"); do { amtp = 1024; err = DCILobRead(svchp, errhp, lobp, &amtp, 1, buf + readsize, lenp + 1 - readsize, (dvoid *)0, (sb4(*)(dvoid *, const dvoid *, ub4, ub1))0, (ub2)0, (ub1)SQLCS_IMPLICIT); if (err == DCI_SUCCESS || err == DCI_NEED_DATA) readsize += amtp; else COMMENT("Read_from_loc : DCILobRead"); } while (err == DCI_NEED_DATA); 147 第5章 程序示例 free(buf); } sword alloc_lob_desc(DCIEnv *envhp, DCILobLocator **lobsrc) { if (DCIDescriptorAlloc(envhp, (dvoid **)lobsrc, (ub4)DCI_DTYPE_LOB, (size_t)0, (dvoid **)0) != DCI_SUCCESS) { printf("FAILED: init_handles()\n"); return DCI_SUCCESS; } return DCI_ERROR; } int main() { text *DbName = (text *)"KingbaseES"; text *username = (text *)"SYSTEM"; text *password = (text *)"MANAGER"; int logged_on = FALSE; DCIDefine *dfnhp[2]; DCILobLocator *lobp[2]; text *sqlstmt = (text *)"SELECT C2,C3 FROM TAB2"; if (init_handles(&envhp, &errhp)) { printf("FAILED: init_handles()\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } if (log_on(envhp, errhp, username, password, DbName)) { printf("FAILED: log_on()\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } logged_on = TRUE; if (DCIHandleAlloc((dvoid *)envhp, (dvoid **)&stmthp, (ub4)DCI_HTYPE_STMT, (CONST size_t)0, (dvoid **)0)) 148 第5章 程序示例 { printf("FAILED: alloc statement handle\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } lobp[0] = (DCILobLocator *)0; lobp[1] = (DCILobLocator *)0; alloc_lob_desc(envhp, &lobp[0]); alloc_lob_desc(envhp, &lobp[1]); if (DCIStmtPrepare(stmthp, errhp, sqlstmt, (ub4)strlen((char *)sqlstmt), (ub4)DCI_NTV_SYNTAX, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIStmtPrepare() select\n"); report_error(errhp); return DCI_ERROR; } dfnhp[0] = (DCIDefine *)0; dfnhp[1] = (DCIDefine *)0; if (DCIDefineByPos(stmthp, &dfnhp[0], errhp, (ub4)1, (dvoid *)&lobp[0], (sb4)4, (ub2)SQLT_CLOB, (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIDefineByPos()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineByPos(stmthp, &dfnhp[1], errhp, (ub4)2, (dvoid *)&lobp[1], (sb4)4, (ub2)SQLT_BLOB, (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIDefineByPos()\n"); report_error(errhp); return DCI_ERROR; } if (DCIStmtExecute(svchp, stmthp, errhp, (ub4)0, (ub4)0, (CONST DCISnapshot *)0, (DCISnapshot *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIStmtExecute() select\n"); 149 第5章 程序示例 report_error(errhp); return DCI_ERROR; } while (1) { if (DCIStmtFetch(stmthp, errhp, 1, DCI_FETCH_NEXT, 0) != DCI_SUCCESS) break; Read_from_loc(svchp, errhp, lobp[0]); Read_from_loc(svchp, errhp, lobp[1]); } DCIDescriptorFree((dvoid *)lobp[0], (ub4)DCI_DTYPE_LOB); DCIDescriptorFree((dvoid *)lobp[1], (ub4)DCI_DTYPE_LOB); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } 5.5 将数据写入大字段 本示例仅展示主函数的实现, 不再重复展示 init_handles、log_on、finish_demo 和 report_error 等函数，以及 包含的头文件列表。 #define COMMENT(x) (void)fprintf(stdout, "\nCOMMENT: %s\n", x) #define WRITESIZE 1024 * 1024 void write_from_loc(DCISvcCtx *svchp, DCIError *errhp, DCILobLocator *lobp) { char *buf = (char *)malloc(sizeof(char) * 1024); ub4 writesize = 0; ub4 amtp; ub4 lenp = 0; sb4 err; COMMENT("Read from the locator."); memset(buf, 'a', 1024); printf("\n--------------------------------------------------------------\n"); do { amtp = 1024; 150 第5章 程序示例 err = DCILobWrite(svchp, errhp, lobp, &amtp, 1, (dvoid *)buf, (ub4)1024, 0, (dvoid *)0, 0, (ub2)0, (ub1)SQLCS_IMPLICIT); if (err == DCI_SUCCESS) writesize += amtp; } while (writesize < WRITESIZE); printf("\n--------------------------------------------------------------\n"); printf("\n"); free(buf); } sword alloc_lob_desc(DCIEnv *envhp, DCILobLocator **lobsrc) { if (DCIDescriptorAlloc(envhp, (dvoid **)lobsrc, (ub4)DCI_DTYPE_LOB, (size_t)0, (dvoid **)0) != DCI_SUCCESS) { printf("FAILED: init_handles()\n"); return DCI_SUCCESS; } return DCI_ERROR; } int main() { text *DbName = (text *)"KingbaseES"; text *username = (text *)"SYSTEM"; text *password = (text *)"MANAGER"; int logged_on = FALSE; DCIDefine *dfnhp[2]; DCILobLocator *lobp[2]; text *sqlstmt = (text *)"SELECT C2, C3 FROM TAB2 WHERE C1=1 FOR UPDATE"; char sql[1024]; if (init_handles(&envhp, &errhp)) { printf("FAILED: init_handles()\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); 151 第5章 程序示例 } if (log_on(envhp, errhp, username, password, DbName)) { printf("FAILED: log_on()\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } logged_on = TRUE; if (DCIHandleAlloc((dvoid *)envhp, (dvoid **)&stmthp, (ub4)DCI_HTYPE_STMT, (CONST size_t)0, (dvoid **)0)) { printf("FAILED: alloc statement handle\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } lobp[0] = (DCILobLocator *)0; lobp[1] = (DCILobLocator *)0; alloc_lob_desc(envhp, &lobp[0]); alloc_lob_desc(envhp, &lobp[1]); strcpy(sql, "INSERT INTO TAB2 VALUES(1, EMPTY_CLOB(), EMPTY_BLOB());"); if (DCIStmtPrepare(stmthp, errhp, (unsigned char *)sql, (ub4)strlen((char *)sql), (ub4)DCI_NTV_SYNTAX, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIStmtPrepare() select\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } if (DCIStmtExecute(svchp, stmthp, errhp, (ub4)1, (ub4)0, (CONST DCISnapshot *)0, (DCISnapshot *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIStmtExecute() select\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } if (DCIStmtPrepare(stmthp, errhp, sqlstmt, (ub4)strlen((char *)sqlstmt), (ub4)DCI_NTV_SYNTAX, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIStmtPrepare() select\n"); report_error(errhp); 152 第5章 程序示例 return DCI_ERROR; } dfnhp[0] = (DCIDefine *)0; dfnhp[1] = (DCIDefine *)0; if (DCIDefineByPos(stmthp, &dfnhp[0], errhp, (ub4)1, (dvoid *)&lobp[0], (sb4)4, (ub2)SQLT_CLOB, (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIDefineByPos()\n"); report_error(errhp); return DCI_ERROR; } if (DCIDefineByPos(stmthp, &dfnhp[1], errhp, (ub4)2, (dvoid *)&lobp[1], (sb4)4, (ub2)SQLT_BLOB, (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIDefineByPos()\n"); report_error(errhp); return DCI_ERROR; } if (DCIStmtExecute(svchp, stmthp, errhp, (ub4)1, (ub4)0, (CONST DCISnapshot *)0, (DCISnapshot *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIStmtExecute() select\n"); report_error(errhp); return DCI_ERROR; } write_from_loc(svchp, errhp, lobp[0]); write_from_loc(svchp, errhp, lobp[1]); DCIDescriptorFree((dvoid *)lobp[0], (ub4)DCI_DTYPE_LOB); DCIDescriptorFree((dvoid *)lobp[1], (ub4)DCI_DTYPE_LOB); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } 153 第5章 程序示例 5.6 DIRPATH 操作 本示例仅展示主函数的实现, 不再重复展示 init_handles、log_on、finish_demo 和 report_error 等函数，以及 包含的头文件列表。 typedef struct _ColAttr_t { ub4 data_offset; ub4 data_size; char *col_name; ub4 data_type; int *indp; } ColAttr_t; void InitColOffset(ColAttr_t *col, ub2 cols, ub4 *record_size) { ub4 offset = 0; int i; for (i = 0; i < cols; i++) { col[i].data_offset = offset; offset += col[i].data_size; } *record_size = offset; } sword SetTableInfo(const char *schema, const char *table, ColAttr_t *col, ub2 cols, ub4 rows, ub4 *nrows, ub1 input_type, DCIDirPathCtx **dpctxpp, DCIDirPathColArray **dpcapp, DCIDirPathStream **dpstrpp, DCIParam **colLstDescpp) { ub2 i, pos; DCIParam *colDesc; ub4 buf_size; ub1 dirpathinput = input_type; ub2 dtype = SQLT_CHR; char dfltdatemask_tbl[100] = "YYYY-MM-DD HH24:MI:SS"; DCIParam *colLstDesc = NULL; DCIDirPathCtx *dpctx = NULL; DCIDirPathColArray *dpca = NULL; DCIDirPathStream *dpstr = NULL; *dpctxpp = NULL; 154 第5章 程序示例 *dpcapp = NULL; *dpstrpp = NULL; *colLstDescpp = NULL; DCIHandleAlloc((dvoid *)envhp, (dvoid **)&dpctx, (ub4)DCI_HTYPE_DIRPATH_CTX, (size_t)0, (dvoid **)0); *dpctxpp = dpctx; DCIAttrSet((dvoid *)dpctx, (ub4)DCI_HTYPE_DIRPATH_CTX, (dvoid *)table, (ub4)strlen((const char *)table), (ub4)DCI_ATTR_NAME, errhp); if (schema && strlen(schema) != 0) { DCIAttrSet((dvoid *)dpctx, (ub4)DCI_HTYPE_DIRPATH_CTX, (dvoid *)schema, (ub4)strlen((const char *)schema), (ub4)DCI_ATTR_SCHEMA_NAME, errhp); } DCIAttrSet((dvoid *)dpctx, (ub4)DCI_HTYPE_DIRPATH_CTX, (dvoid *)dfltdatemask_tbl, (ub4)strlen((const char *)dfltdatemask_tbl), (ub4)DCI_ATTR_DATEFORMAT, errhp); DCIAttrSet((dvoid *)dpctx, DCI_HTYPE_DIRPATH_CTX, (dvoid *)&dirpathinput, (ub4)0, DCI_ATTR_DIRPATH_INPUT, errhp); DCIAttrSet((dvoid *)dpctx, (ub4)DCI_HTYPE_DIRPATH_CTX, (dvoid *)&cols, (ub4)0, (ub4)DCI_ATTR_NUM_COLS, errhp); DCIAttrGet((dvoid *)dpctx, DCI_HTYPE_DIRPATH_CTX, (dvoid *)&colLstDesc, (ub4 *)0, DCI_ATTR_LIST_COLUMNS, errhp); for (i = 0, pos = 1; i < cols; i++, pos++) { DCIParamGet((CONST dvoid *)colLstDesc, (ub4)DCI_DTYPE_PARAM, errhp, (dvoid **)&colDesc, pos); *colLstDescpp = colLstDesc; DCIAttrSet((dvoid *)colDesc, (ub4)DCI_DTYPE_PARAM, (dvoid *)col[i].col_name, (ub4)strlen(col[i].col_name), 155 第5章 程序示例 (ub4)DCI_ATTR_NAME, errhp); if (dirpathinput == DCI_DIRPATH_INPUT_STREAM) { DCIAttrSet((dvoid *)colDesc, (ub4)DCI_DTYPE_PARAM, (dvoid *)&col[i].data_type, (ub4)0, (ub4)DCI_ATTR_DATA_TYPE, errhp); } else { DCIAttrSet((dvoid *)colDesc, (ub4)DCI_DTYPE_PARAM, (dvoid *)&dtype, (ub4)0, (ub4)DCI_ATTR_DATA_TYPE, errhp); } DCIAttrSet((dvoid *)colDesc, (ub4)DCI_DTYPE_PARAM, (dvoid *)&col[i].data_size, (ub4)0, (ub4)DCI_ATTR_DATA_SIZE, errhp); DCIDescriptorFree((dvoid *)colDesc, DCI_DTYPE_PARAM); *colLstDescpp = NULL; } buf_size = 64 * 1024; DCIAttrSet((dvoid *)dpctx, (ub4)DCI_HTYPE_DIRPATH_CTX, (dvoid *)&buf_size, (ub4)0, (ub4)DCI_ATTR_BUF_SIZE, errhp); DCIDirPathPrepare(dpctx, svchp, errhp); DCIHandleAlloc((dvoid *)dpctx, (dvoid **)&dpca, (ub4)DCI_HTYPE_DIRPATH_COLUMN_ARRAY, (size_t)0, (dvoid **)0); *dpcapp = dpca; DCIAttrGet((CONST dvoid *)dpca, DCI_HTYPE_DIRPATH_COLUMN_ARRAY, (dvoid *)(nrows), (ub4 *)0, DCI_ATTR_NUM_ROWS, errhp); DCIHandleAlloc((dvoid *)dpctx, (dvoid **)&dpstr, (ub4)DCI_HTYPE_DIRPATH_STREAM, (size_t)0, (dvoid **)0); *dpstrpp = dpstr; return DCI_SUCCESS; } 156 第5章 程序示例 sword FreeDirPathHandle( DCIParam *colLstDesc, DCIDirPathCtx *dpctx, DCIDirPathColArray *dpca, DCIDirPathStream *dpstr ) { if (colLstDesc != NULL) DCIDescriptorFree((dvoid *)colLstDesc, DCI_DTYPE_PARAM); if (dpca != NULL) DCIHandleFree((dvoid *)dpca, DCI_HTYPE_DIRPATH_COLUMN_ARRAY); if (dpstr != NULL) DCIHandleFree((dvoid *)dpstr, DCI_HTYPE_DIRPATH_STREAM); if (dpctx != NULL) DCIHandleFree((dvoid *)dpctx, DCI_HTYPE_DIRPATH_CTX); return DCI_SUCCESS; } sword DirPathLoadStream(const char *schema, const char *table, ColAttr_t *col, ub2 cols, ub4 rows, void *data, ub1 input_type) { sword retcode; ub4 rowoff; ub4 rowoff_all = 0; ub2 coloff; ub4 record_size = 0; ub4 nrows; ub4 times = 0; ub4 rows_temp; DCIParam *colLstDesc = NULL; DCIDirPathCtx *dpctx = NULL; DCIDirPathColArray *dpca = NULL; DCIDirPathStream *dpstr = NULL; if (table == NULL || col == NULL) return DCI_ERROR; if (cols == 0) return DCI_ERROR; InitColOffset(col, cols, &record_size); 157 第5章 程序示例 if (!SetTableInfo(schema, table, col, cols, rows, &nrows, input_type, &dpctx, &dpca, &dpstr, &colLstDesc)) return DCI_ERROR; while (rows) { if (rows > nrows) { rows_temp = nrows; rows -= nrows; } else { rows_temp = rows; rows = 0; } retcode = DCIDirPathColArrayReset(dpca, errhp); if (retcode != DCI_SUCCESS) return DCI_ERROR; retcode = DCIDirPathStreamReset(dpstr, errhp); if (retcode != DCI_SUCCESS) return DCI_ERROR; for (rowoff = 0; rowoff < rows_temp; rowoff++) { for (coloff = 0; coloff < cols; coloff++) { if (col[coloff].indp && col[coloff].indp[rowoff_all] == -1) { retcode = DCIDirPathColArrayEntrySet(dpca, errhp, rowoff, coloff, (ub1 *)data + (rowoff_all * record_size) + col[coloff].data_offset,col[coloff].data_size, DCI_DIRPATH_COL_NULL); if (retcode != DCI_SUCCESS) return DCI_ERROR; } else { retcode = DCIDirPathColArrayEntrySet(dpca, errhp, rowoff, coloff, (ub1 *)data + (rowoff_all * record_size) + col[coloff].data_offset,col[coloff].data_size, DCI_DIRPATH_COL_COMPLETE); if (retcode != DCI_SUCCESS) 158 第5章 程序示例 return DCI_ERROR; } } rowoff_all++; } retcode = DCIDirPathColArrayToStream(dpca, dpctx, dpstr, errhp, rows_temp, 0); if (retcode != DCI_SUCCESS) return DCI_ERROR; retcode = DCIDirPathLoadStream(dpctx, dpstr, errhp); if (retcode != DCI_SUCCESS) return DCI_ERROR; } retcode = DCIDirPathDataSave(dpctx, errhp, (ub4)DCI_DIRPATH_DATASAVE_FINISH); if (retcode != DCI_SUCCESS) return DCI_ERROR; retcode = DCIDirPathFinish(dpctx, errhp); if (retcode != DCI_SUCCESS) return DCI_ERROR; FreeDirPathHandle(colLstDesc, dpctx, dpca, dpstr); return DCI_SUCCESS; } 5.7 批量插入 本示例仅展示主函数的实现, 不再重复展示 init_handles、log_on、finish_demo 和 report_error 等函数，以及 包含的头文件列表。 /* 假定表 TESTTAB 的结构为 * TESTTAB(COL1 NUMBER, COL2 VARCHAR2(30)) * create table testtab(col1 number, col2 varchar2(30)); */ #define BATCH_ARRAY_CNT 100 #define COL2_MAX_LEN 32 159 第5章 程序示例 sword Test_Batch_Insert() { int i, cFetchRows; char sql[256] = ""; DCIBind *pDciBind = NULL; int col1_array[BATCH_ARRAY_CNT] = {0}; char col2_array[BATCH_ARRAY_CNT][COL2_MAX_LEN] = {0}; if (DCIHandleAlloc((void *)envhp, (void **)&stmthp, (const ub4)DCI_HTYPE_STMT, 0, NULL)) { printf("FAILED: DCIHandleAlloc() DCI_HTYPE_STMT.\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } strcpy(sql, "insert into TESTTAB values(:col1, :col2) "); if (DCIStmtPrepare(stmthp, errhp,(DciText *)sql, (ub4)strlen(sql),DCI_NTV_SYNTAX, DCI_DEFAULT)) { printf("FAILED: DCIStmtPrepare() col1.\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } if (DCIBindByPos(stmthp, &pDciBind, errhp, 1, col1_array, sizeof(int), SQLT_INT, (void *)0, (ub2 *)0, (ub2 *)0, (ub4)0,(ub4 *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIBindByPos() col1.\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } if (DCIBindArrayOfStruct(pDciBind, errhp, sizeof(int), 0, 0, 0)) { printf("FAILED: DCIBindArrayOfStruct() col1.\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } if (DCIBindByPos(stmthp, &pDciBind, errhp, 2, col2_array, COL2_MAX_LEN, SQLT_CHR, (void *)0, (ub2 *)0, (ub2 *)0, (ub4)0,(ub4 *)0, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIBindByPos() col2.\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } 160 第5章 程序示例 if (DCIBindArrayOfStruct(pDciBind, errhp, COL2_MAX_LEN, 0, 0, 0)) { printf("FAILED: DCIBindArrayOfStruct() col2.\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } for (i = 0; i < BATCH_ARRAY_CNT; i++) { col1_array[i] = 60 + i; snprintf(col2_array[i], COL2_MAX_LEN, "%s%d", "TestBatchInsert-", 60+i); } if (DCIStmtExecute(svchp, stmthp, errhp, BATCH_ARRAY_CNT, (ub4)0, NULL, NULL, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIStmtExecute() batch insert.\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } if (DCIAttrGet(stmthp, DCI_HTYPE_STMT, &cFetchRows, 0, DCI_ATTR_ROW_COUNT, errhp)) { printf("FAILED: DCIStmtExecute() batch insert.\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } if (cFetchRows != BATCH_ARRAY_CNT) { printf("Expected: %d all success, but only %d rows inserted!!!\n", BATCH_ARRAY_CNT, cFetchRows); return DCI_ERROR; } else { printf("%d rows insert successfully.\n", cFetchRows); } if (DCITransCommit(svchp, errhp, (ub4)DCI_DEFAULT)) { printf("FAILED: DCIStmtExecute() batch insert.\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } if (DCIHandleFree((void *)stmthp, (const ub4)DCI_HTYPE_STMT)) { 161 第5章 程序示例 printf("FAILED: DCIStmtExecute() batch insert.\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } return DCI_SUCCESS; } int main() { text *DbName = (text *)"KingbaseES"; text *username = (text *)"SYSTEM"; text *password = (text *)"MANAGER"; char sql[1024]; if (init_handles(&envhp, &errhp)) { printf("FAILED: init_handles()\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } if (log_on(envhp, errhp, username, password, DbName)) { printf("FAILED: log_on()\n"); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } logged_on = TRUE; Test_Batch_Insert(); return finish_demo(logged_on, envhp, svchp, errhp, stmthp); } 162 第 6 章 附录-DCI 错误码 6 第 章 附录-DCI 错误码 表 6.1: DCI 错误码 错误代码 解释 1 重复键违反唯一约束。 942 “T”关系不存在。 1014 KingbaseES 数据库为关闭状态。 1019 不能在用户端释放内存。 1034 程序列查询错误或无法连接到服务器。 1036 非法的变量名称/数。 1092 通信链路故障。 1335 尚未实现的特性。 1405 获取到的列的值为 NULL。 1653 无法扩展关系。 1867 时间间隔无效。 1877 缓冲空间太小。 2800 查询超时。 3114 未连接到 KingbaseES 数据库。 21560 值大小不能为负数或句柄值为 NULL。 22056 值 [%f] 除以 0。 22289 不能对未打开的文件或者 LOB 执行%s 操作。 见续表 163 第 6 章 附录-DCI 错误码 表 6.1 – 续表 错误代码 解释 22293 LOB 已在同样的事务中打开。 22920 包含 LOB 值的行未被锁定。 24305 错误的绑定或定义上下文。 24306 缓冲区损坏。 24307 无效长度。 24333 具有仅描述模式的无效语句类型。 24801 DCI lob 函数中含有非法参数值。 24811 提供的写入数据少于声明的数量。 24854 提供的碎片信息无效。 65001 无法找到 sys_service.conf 文件，或参数数组越界，请减少占位符参数。 164 版权声明 版权声明 北京人大金仓信息技术股份有限公司（简称：人大金仓）版权所有，并保留对本手册及本声明的一切权利。 未得到人大金仓的书面许可，任何人不得以任何方式或形式对本手册内的任何部分进行复制、摘录、备份、修 改、传播、翻译成其他语言、将其全部或部分用于商业用途。 免责声明 本手册内容依据现有信息制作，由于产品版本升级或其他原因，其内容有可能变更。人大金仓保留在没有任何通 知或者提示的情况下对手册内容进行修改的权利。 本手册仅作为使用指导，人大金仓在编写本手册时已尽力保证其内容准确可靠，但并不确保手册内容完全没有错 误或遗漏，本手册中的所有信息也不构成任何明示或暗示的担保。 技术支持 • 人大金仓官方网站：http://www.kingbase.com.cn/ • 人大金仓文档中心：http://help.kingbase.com.cn/ • 全国服务热线：400-601-1188 • 人大金仓技术支持与反馈信箱：support@kingbase.com.cn 165 服务周期承诺 服务周期承诺 由于市场需求在不断变化，技术创新和发展的进程不断加剧，产品的版本更迭不可避免。人大金仓对于产品版本 生命周期的有效管理，有助于您提前规划项目，更好地从产品服务终止上过渡。 表 2: KingbaseES 产品生命周期里程碑 关键里程碑点 定义 产品发布日期 产品正式发布版本，即 GA（general availability）版本的发布日期。 停止销售日期 正式停止销售的日期，版本停止接受订单日。该日之后，产品将不再销售。 停止功能升级日期 在该日期之后，不再提供新特性和新硬件支持。但依旧提供错误修复、安全修复、功 能维护等服务。 停止功能维护日期 在该日期之后，不再维护功能，修复问题。但依旧提供安全修复等服务 停止安全维护日期 在该日期之后，不再发布补丁版本修复中高风险漏洞，仅提供有限的支持。 产品服务终止日期 停止提供产品服务和支持的日期。包括软件维护版本，缺陷修复，以及针对该产品的 所有服务支持（包括服务热线和远程/现场支持）。 服务周期策略 金仓数据库管理系统 KingbaseES 产品确保以下的服务周期： 1）产品自发布之日起至产品停止功能升级（包含新特性、新硬件支持）之日不少于 5 年。 2）产品停止功能升级之日起至产品停止功能维护（主要包括问题修复）之日不少于 4 年。 3）产品功能维护停止之日起至产品停止安全维护（包括中高风险漏洞修复）之日不少于 2 年。 服务终止策略 金仓数据库管理系统 KingbaseES 产品确保在销售后，至少提供 6 年的服务支持。 注意: 人大金仓将会综合各方因素来确定产品服务终止日期。并将在实际产品服务终止日期之前至少 90 天，通过公 166 服务周期承诺 开方式宣布产品服务终止日期。 167