数字有机体数据库系统用户手册

Transcription

1 十年一日, 深入成就深度业精于专, 专注成就专业 成都天心悦高科技发展有限公司 2015 年 10 月

2 版权声明 数字有机体工作库 (DosSQL) 及其客户端驱动的版权属于成都天心悦高科技发展有限公司所有 任何组织和个人未经成都天心悦高科技发展有限公司许可与授权, 不得擅自使用 复制 更改该软件的产品 本软件受版权法和国际条约的保护 如未经授权而擅自使用 复制或传播本软件程序 ( 或其中任何部分 ), 将受到严厉的刑事及民事制裁, 并将在法律许可的范围内受到最大可能的起诉! 版权所有, 盗版必究! c 成都天心悦高科技发展有限公司地址 : 成都市武侯区棕南小区电话 : 邮编 :610054

3 目录 1 前言 编写约定 如何使用本手册 相关文档说明 术语 如何获得技术支持 简介 数字有机体系统简介 数字有机体工作库简介 接口概述 API 和库 C API C API 简介 C API 数据类型 C API 函数概述 C API 函数描述 C API 预处理语句 C API 预处理语句的数据类型 C API 预处理语句函数概述 C API 预处理语句函数描述 C API 预处理语句方面的问题 多查询执行的 C API 处理 日期和时间值的 C API 处理 C API 线程函数介绍 创建客户端程序 编程示例 PERL API 简介 详细使用说明 PHP API PYTHON API TCL API 连接器 DOSODBC 简介 安装 详细使用说明 JDBC JDBC 简介... 93

4 4.2.2 安装 详细使用说明 新增错误类型 SQL 语句中使用多个数据库 创建伪线程失败 伪线程执行失败 数据库名长度不合法 修改数据库属性 目录重构 执行不支持的命令 备份数据库 常见问题解决 注意事项 常见问题与解答

5 成都天心悦高科技发展有限公司 1 前言 1.1 编写约定 非常感谢您使用成都天心悦高科技发展有限公司的产品, 本公司将竭诚为您提供最好的服务 本手册假定用户能够理解并使用 Linux 的基本 shell 命令 文中出现的 # 号表示数字有机体系统的命令行提示符 文中没有特特说明是批量同步工作库时, 默认表示实时同步工作库 命令格式描述中的斜体字表示应由用户填充的部分, [ ] 表示命令中可选的命令参数 为了阅读方便, 文档以灰底黑框的形式呈现某些重要的配置操作 不过, 由于数字有机体系统和 Windows 采用不同的字符集和文本规范, 请不要直接拷贝文档中的命令行或者配置行到数字有机体系统中, 请重新输入 因软件更新, 本手册可能包含技术上不准确的地方或文字错误 本手册的内容将做定期的更新, 恕不另行通知 ; 更新的内容将会在本手册的新版本中加入 本公司随时会改进或更新本手册中描述的产品或程序 1.2 如何使用本手册 本手册的阅读对象为数字有机体工作库的应用软件开发人员, 建议首先阅读第二章了解本文的内容和开发注意事项, 然后根据自己使用的需要选择章节进行阅读 若遇到问题请阅读第 5 章了解新增错误类型, 如何解决请查阅第六章 如果需要查找某个接口函数或者数据结构, 可以直接通过目录查找 1.3 相关文档说明 数字有机体系统包括数字有机体工作平台和数字有机体工作库, 本文档是数字有机体工作库的开发手册, 相关的其他文档还有 : 有关数字有机体工作平台的使用请参阅 数字有机体工作平台及抗毁容灾系统用户手册 有关如何在数字有机体工作平台上开发应用程序, 请参考 数字有机体工作平台及抗毁容灾系统开发手册 有关如何安装 管理 维护和使用数字有机体工作库请参考 数字有机体工作库及大规模存储与管理系统用户手册 第 1 页

6 数字有机体工作库及大规模存储与管理系统开发手册 1.4 术语 数字有机体工作库及大规模存储与管理系统 : 我们有时将数字有机体工作库及大规模存储与管理系统简称为数字有机体工作库或工作库, 英文缩写为 DosSQL 这种工作库含盖常规数据库系统但远高于常规数据库系统, 是一个在 Mysql 之上的 面向很多应用的 统一的 人能化的应用数据平台 1.5 如何获得技术支持 在您遇到问题时, 请首先联系您的产品提供商 大多数问题都可以在产品提供商的技术支持人员的帮助下得以解决 您也可以通过产品提供商致电本公司的技术服务热线 : , 获得电话技术支持 您还可以发送邮件, 邮件地址是 :tianxinyue@126.com 如果您确实需要本公司提供上门服务, 本公司将竭诚为您服务 第 2 页

7 成都天心悦高科技发展有限公司 2 简介 2.1 数字有机体系统简介 数字有机体系统 ( 英文名称为 Digital Oganism System, 缩写为 DOS) 是在刘心松教授带领下, 由成都天心悦高科技发展有限公司的研发人员前后千余人次, 经过三十多年的技术积累, 研发成功的基础系统 研发这种系统的原始宗旨是向生物特别是人类个体和群体的结构 机理和特性逼近, 是一种人能化的新的系统模式 这种系统集操作系统 数据库系统 大规模存储 抗毁容灾 高伸缩 高智能 高灵活 自搜索 自传播 自复制 自修复 自重构 自适应 系统间的兼容性 群体间的协作性 对资源的动态管理调度合理配置 大小新旧机器混合使用等特性为一体, 是一个整体解决方案, 是面向所有应用的统一的 ( 应用 ) 系统平台 数字有机体系统主要由数字有机体工作平台及抗毁容灾系统 数字有机体工作库及大规模存储与管理系统和数字有机体安全系统组成 这是从底层作起的一个一体化平台, 可以在此平台上开发任何应用, 形成任何应用系统 例如现在已有的应用系统就有数字有机体流媒体系统 数字有机体监控系统 数字有机体会议系统 数字有机体网关 数字有机体管理系统 数字有机体控申系统 数字有机体侦查指挥系统等 本文有时将数字有机体工作平台及抗毁容灾系统, 数字有机体工作库及大规模存储与管理系统和数字有机体安全系统统称为数字有机体系统 数字有机体工作平台及抗毁容灾系统含盖常规操作系统但远高于常规操作系统, 是一个在 Linux 之上的 面向很多应用的 统一的 人能化的应用系统平台 数字有机体工作库及大规模存储与管理系统含盖常规数据库系统但远高于常规数据库系统, 是一个在 Mysql 之上的 面向很多应用的 统一的 人能化的应用数据平台 有时将数字有机体工作平台及抗毁容灾系统简称为数字有机体工作平台甚至工作平台 有时将数字有机体工作库及大规模存储与管理系统简称为数字有机体工作库甚至工作库 2.2 数字有机体工作库简介 数字有机体工作库由接口子系统 通信子系统 执行子系统和管理子系统四个部分构成, 各子系统相互协作实现相关功能 可以由大量的服务器通过高速网络连接, 构成一个超大型数字有机体工作库 由于系统具有高存储容量 高动态伸缩性 高可用性等特点, 它可以为电子政务 视频点播 校园网等对数据库可靠性要求高 存储容量大的多种应用场合提供数据 ( 管理 ) 平台 它具有如下主要的功能和特性 : 1) 海量存储系统支持很多库, 单库支持至少 TB 级数据存储 系统存储容量可根据用户数据的存 第 3 页

8 数字有机体工作库及大规模存储与管理系统开发手册 储需求动态扩展, 能够支持大量视频 音频等多媒体数据, 同时能够存储多种文本数据以及二进制格式的软件, 能够满足多种应用需求 2) 分布性系统的分布性主要体现在数据分布性 执行分布性以及管理分布性 数据分布性指系统的所有用户数据根据可靠性以及执行效率的要求分布在系统中的各个节点, 它们之间没有主次之分, 是完全对等的关系 执行分布性乃指用户的每一条库操作指令能够被系统自动解析, 选择最佳的服务器节点完成, 缩短响应时间, 比单机数据库系统的操作效率有显著的提高, 特别是复杂操作, 效率可以成倍的提高 管理分布性指整个系统的维护和管理分布在所有的节点上, 不存在核心节点或中心节点, 也没有主次之分, 这样既保证了高可靠性, 又避免了系统瓶颈 3) 并行性系统的并行性主要体现在操作并行性和管理并行性 操作并行性指用户的不同操作在不同节点并行处理, 同时根据需要用户的同一操作也可在不同的节点上并行处理, 这样既提高了操作的效率, 又加大了系统的吞吐量 管理并行性指对整个系统的维护在不同的节点上并行进行, 通过特定的协议协调和维护它们之间的一致性, 这样既提高了系统管理的效率, 同时又保证了高可靠性 这是集中式系统或单机系统以及 Cluster 系统无法做到的, 是数字有机体工作库区别于其它数据库系统的显著特征之一 4) 动态伸缩性动态伸缩性指系统的规模 服务能力能够根据需要进行动态配置, 而不是象单机系统那样, 服务能力从一开始就定死并受限于服务器的性能指标 系统能够动态地增加 减少服务器节点的数量, 根据需要动态地改变服务能力, 可以由大量服务器组成的系统提供服务, 同时也可动态地更换或升级系统中的服务器, 而不影响整个系统的正常使用 因此可以根据业务量的增长需求分期分批投资和建设 5) 高可靠性及高可用性系统根据用户对工作库的使用频率 可靠性要求以及配置情况, 动态决定工作库的分布以及冗余度, 从而保证用户数据的可用性 同时在一定环境下系统能够自动进行重构, 这样在发生节点故障时, 系统通过自动重构用户的数据分布和分离故障节点就能保证用户数据的高可靠性及高可用性 6) 高安全性系统除具有一般数据库系统的安全特性外还提供远程数据同步功能, 能够通过广域网络将系统中的数据从本地导出到远地存储, 也可以方便地将数据从远地导入, 因此即使发生灾难性事故也能保证数据的安全 数据通信支持 SSL 安全通信, 并采用证书的机制防止主机的伪冒, 具备主机识别的功能等 7) 使用方便性系统提供多种接口, 方便用户的二次开发 系统支持多种开发工具, 如 ODBC JDBC 等, 支持 C/C++ Perl JAVA PHP 等高级程序语言, 能够开发动态网页等各种数据库应用程序 8) 硬件通用性 第 4 页

9 成都天心悦高科技发展有限公司 系统使用的各种硬件设备均为通用设备, 构建系统方便灵活, 维护简单 2.3 接口概述 为了兼容现有的大多数 MySQL 应用程序, 并缩短编程人员学习新系统的时间, 数字有机体工作库的接口通过 MySQL 的原有接口提供 为了兼容现有的大多数 Linux 程序, 并缩短编程人员学习新系统的时间, 数字有机体工作库的接口通过 MySQL 的原有接口提供 不过, 根据数字有机体工作库的需要, 扩充了 SQL 指令集, 并修改了部分底层功能 因此, 不要采用原有的 MySQL 接口来访问数字有机体工作库, 而应当采用数字有机体工作库提供的接口库 同样, 数字有机体工作库和 MySQL 在体系结构上是完全不同的 因此, 少量只适用于单机环境的 SQL 指令在数字有机体工作库上也不再有意义或者不可能在存在了 请查阅本手册中 不支持特性章节 因此, 少量只适用于单机环境的 SQL 指令在数字有机体工作库上也不再有意义或者不可能再存在了 请查阅 数字有机体用户手册 中 不支持特性章节 DosSQL 提供 C API C++ API JDBC(JAVA API) Perl API HPH API Python API Tcl API 本手册向用户提供数字有机体工作库(DosSQL 当前版本 ) 的开发接口使用说明, 将重点介绍常用的 C API JDBC 和 Perl API 基于数字有机体工作库开发大数据量 大并发 高性能的应用时, 推荐采用分表 分库 读写连接分离等技术, 这将大幅度提升应用的性能 开发接口因计算机系统平台 ( 如 Windows 和 Linux) 和开发语言而有所差异,DosSQL 支持多种系统平台和语言的应用开发, 将介绍的内容如下 开发库名称 CAPI 组件名称 组件类型 系统平台 编程语言 libmysqlclient.so( 或.dll) 开发库文件和 Windows/Linux c/c++ libmysqlclient_r.so( 或.dll) 头文件 libmysqlclient.a( 或.lib) libmysqlclient_r.a( 或.lib) mysql.h 等文件 JDBC dossql-connector-java jar 库文件 Windows/Linux Java PERL Perl DBI DBI 是数据库 Linux perl Perl DBD C API 的通用接口, DBD 是数据库驱动程序 示例 位于 /usr/local/dossql/demo/ 目录 示例程序 linux c/c++ 第 5 页

10 第 6 页 数字有机体工作库及大规模存储与管理系统开发手册

11 成都天心悦高科技发展有限公司 3 API 和库 本章将介绍 DosSQL 可使用的 API, 以及如何使用它们 将详细介绍 C API, 这是因 为它是开发人员经常用到的, 而且它也是大多数其他 API 的基础 3.1 C API C API 简介 C API 是数字有机体工作库提供的以 C 库形式存在的基础接口库, 是许多其他 API 接口的基础, 也是 C/C++ 语言常用的编程接口, 它包含在 mysqlclient 库中 大多数其他客户端 API( 除 Connector/J 和 Connector/NET 外 ) 采用 mysqlclient 库来与数字有机体工作库进行通信 这意味着你可以使用很多相同环境变量带来的好处, 这是因为它们是从库中引用的 客户端具有最大的通信缓冲区大小, 初始分配的缓冲区大小 (16KB) 将自动增加到最大 ( 最大为 16MB) 由于缓冲区大小将按需增加, 简单地增加到默认的最大限制, 从其本身来说不会增加资源使用 该限制检查主要是检查错误查询和通信信息包 通信缓冲区必须足够大, 足以包含 1 条 SQL 语句 ( 用于客户端 - 服务器通信 ) 以及 1 行返回的数据 ( 用于服务器 - 客户端通信 ) 每个线程的通信缓冲区将动态增加, 以处理直至最大限制的任何查询或行 例如, 如果 BLOB 值包含高达 16MB 的数据, 那么通信缓冲区的大小限制至少为 16MB( 在服务器和客户端 ) 客户端的默认最大值为 16MB, 服务器的默认最大值也为 16MB 可以在启动服务器时通过更改 max_allowed_packet 参数的值增加它 每次查询后, 数字有机体工作库服务器会将通信缓冲区的大小降至 net_buffer_length 字节 对于客户端, 不会降低与连接相关缓冲区大小, 直至连接关闭为止 此时, 客户端内存将被收回 C API 数据类型 MYSQL 该结构代表 1 个数据库连接的句柄, 几乎所有的 MySQL 函数均使用它 不应尝试拷贝 MYSQL 结构, 不保证这类拷贝结果会有用 MYSQL_RES 该结构代表返回行的查询结果 (SELECT, SHOW, DESCRIBE, EXPLAIN), 在本节的剩余部分, 将查询返回的信息称为 结果集 MYSQL_ROW 这是 1 行数据的 类型安全 表示 它目前是按照计数字节字符串的数组实施的 ( 如果字段值可能包含二进制数据, 不能将其当作由 Null 终结的字符串对待, 这是因为这类值可能会包含 Null 字节 ) 行是通过调用 mysql_fetch_row() 获得的 第 7 页

12 数字有机体工作库及大规模存储与管理系统开发手册 MYSQL_FIELD 该结构包含关于字段的信息, 如字段名 类型和大小, 这里详细介绍了其成员 通过重复调用 mysql_fetch_field(), 可为每个字段获得 MYSQL_FIELD 结构 字段值不是该结构的组成部份, 它们包含在 MYSQL_ROW 结构中 MYSQL_FIELD_OFFSET 这是 MySQL 字段列表偏移量的 类型安全 表示 ( 由 mysql_field_seek() 使用 ) 偏移量是行内的字段编号, 从 0 开始 my_ulonglong 用于行数以及 mysql_affected_rows() mysql_num_rows() 和 mysql_insert_id() 的类型 该类型提供的范围为 0~1.84e19 在某些系统上, 不能打印类型 my_ulonglong 的值 要想打印这类值, 请将其转换为无符号长整数类型并使用 %lu 打印格式 例如 printf ("Number of rows: %lu\n", (unsigned long) mysql_num_rows(result)); 下面列出了 MYSQL_FIELD 结构包含的成员 : char * name 字段名称, 由 Null 终结的字符串 如果用 AS 子句为该字段指定了别名, 名称的值也是别名 char * org_name 段名称, 由 Null 终结的字符串, 忽略别名 char * table 如果该字段不是计算出的字段的话, 它包含该字段的表的名称 对于计算出的字段, 它是空字符串 如果用 AS 子句为该表指定了别名, 它的值是别名 char * org_table 表的名称, 由 Null 终结的字符串, 忽略别名 char * db 字段源自数据库的名称, 由 Null 终结的字符串 如果该字段是计算出的字段, 则 db 即为空的字符串 char * catalog catalog 名称, 该值总是 "def" char * def 该字段的默认值, 由 Null 终结的字符串 仅当使用 mysql_list_fields() 时才设置它 unsigned long length 字段的宽度 unsigned long max_length 用于结果集的字段的最大宽度 ( 对于实际位于结果集中的行, 最长字段值的长度 ) 如果使用 mysql_store_result() 或 mysql_list_fields(), 它将包含字段的最大长度 如果使用 mysql_use_result(), 该变量的值为 0 unsigned int name_length 第 8 页

13 成都天心悦高科技发展有限公司 名称的长度 unsigned int org_name_length org_name 的长度 unsigned int table_length 表名的长度 unsigned int org_table_length org_table 的长度 unsigned int db_length db 的长度 unsigned int catalog_length catalog 的长度 unsigned int def_length def 的长度 unsigned int flags 用于字段的不同 位标志, 标志的值可以有 0 个或多个下述位的集合 : 标志值 标志描述 NOT_NULL_FLAG PRI_KEY_FLAG UNIQUE_KEY_FLAG MULTIPLE_KEY_FLAG UNSIGNED_FLAG ZEROFILL_FLAG BINARY_FLAG AUTO_INCREMENT_FLAG 字段不能为 NULL 字段是主键的组成部分字段是唯一键的组成部分字段是非唯一键的组成部分字段具有 UNSIGNED 属性字段具有 ZEROFILL 属性字段具有 BINARY 属性字段具有 AUTO_INCREMENT 属性 ENUM_FLAG 字段是 ENUM( 不再重视 ) SET_FLAG 字段是 SET( 不再重视 ) BLOB_FLAG 字段是 BLOB 或 TEXT( 不再重视 ) TIMESTAMP_FLAG 字段是 TIMESTAMP( 不再重视 ) 不再重视 BLOB_FLAG ENUM_FLAG SET_FLAG 和 TIMESTAMP_FLAG 标志, 原因在于, 它们指出了字段的类型, 而不是类型的属性 更可取的方式是使用 MYSQL_TYPE_BLOB MYSQL_TYPE_ENUM MYSQL_TYPE_SET 或 MYSQL_TYPE_TIMESTAMP 测试 field->type 在下面的示例中, 介绍了标志值的典型用法 : if (field->flags & NOT_NULL_FLAG) printf("field can't be null\n"); 可以使用下表的宏来测试标志值的布尔状态 : 第 9 页

14 数字有机体工作库及大规模存储与管理系统开发手册 标志状态 描述 IS_NOT_NULL(flags) 如果该字段定义为 NOT NULL, 为 真 IS_PRI_KEY(flags) 如果该字段是主键, 为 真 IS_BLOB(flags) 如果该字段是 BLOB 或 TEXT, 为 真 ( 不再重视, 用测试 field->type 取而代之 ) unsigned int decimals 用于数值字段的十进制数数目 unsigned int charset_nr 用于字段的字符集编号 enum enum_field_types type 字段的类型, 类型值可以是下表所列的 MYSQL_TYPE_ 符号之一 : 类型值 类型描述 MYSQL_TYPE_TINY TINYINT 字段 MYSQL_TYPE_SHORT SMALLINT 字段 MYSQL_TYPE_LONG INTEGER 字段 MYSQL_TYPE_INT24 MEDIUMINT 字段 MYSQL_TYPE_LONGLONG BIGINT 字段 MYSQL_TYPE_DECIMAL DECIMAL 或 NUMERIC 字段 MYSQL_TYPE_NEWDECIMAL 精度数学 DECIMAL 或 NUMERIC MYSQL_TYPE_FLOAT FLOAT 字段 MYSQL_TYPE_DOUBLE DOUBLE 或 REAL 字段 MYSQL_TYPE_BIT BIT 字段 MYSQL_TYPE_TIMESTAMP TIMESTAMP 字段 MYSQL_TYPE_DATE DATE 字段 MYSQL_TYPE_TIME TIME 字段 MYSQL_TYPE_DATETIME DATETIME 字段 MYSQL_TYPE_YEAR YEAR 字段 MYSQL_TYPE_STRING CHAR 字段 MYSQL_TYPE_VAR_STRING VARCHAR 字段 MYSQL_TYPE_BLOB BLOB 或 TEXT 字段 ( 使用 max_length 来确定最大长度 ) MYSQL_TYPE_SET SET 字段 MYSQL_TYPE_ENUM ENUM 字段 MYSQL_TYPE_GEOMETRY Spatial 字段 MYSQL_TYPE_NULL NULL-type 字段 MYSQL_TYPE_CHAR 不再重视, 用 MYSQL_TYPE_TINY 取代 第 10 页

15 成都天心悦高科技发展有限公司 可以使用 IS_NUM() 宏来测试字段是否具有数值类型 将类型值传递给 IS_NUM(), 如果字段为数值类型, 会将其评估为 真 : if (IS_NUM(field->type)) printf("field is numeric\n"); C API 函数概述 这里归纳了 C API 可使用的函数, 并在下一节详细介绍它们 函数 描述 mysql_affected_rows() 返回上次 UPDATE DELETE 或 INSERT 查询更改 / 删除 / 插入的行数 mysql_autocommit() 切换 autocommit 模式,ON/OFF mysql_change_user() 更改打开连接上的用户和数据库 mysql_charset_name() 返回用于连接的默认字符集的名称 mysql_close() 关闭服务器连接 mysql_commit() 提交事务 mysql_data_seek() 在查询结果集中查找属性行编号 mysql_debug() 用给定的字符串执行 DBUG_PUSH mysql_dump_debug_info() 让服务器将调试信息写入日志 mysql_errno() 返回上次调用的 MySQL 函数的错误编号 mysql_error() 返回上次调用的 MySQL 函数的错误消息 mysql_fetch_field() 返回下一个表字段的类型 mysql_fetch_field_direct() 给定字段编号, 返回表字段的类型 mysql_fetch_fields() 返回所有字段结构的数组 mysql_fetch_lengths() 返回当前行中所有列的长度 mysql_fetch_row() 从结果集中获取下一行 mysql_field_seek() 将列光标置于指定的列 mysql_field_count() 返回上次执行语句的结果列的数目 mysql_field_tell() 返回上次 mysql_fetch_field() 所使用字段光标的位置 mysql_free_result() 释放结果集使用的内存 mysql_get_host_info() 返回描述连接的字符串 mysql_get_server_version() 以整数形式返回服务器的版本号 mysql_get_proto_info() 返回连接所使用的协议版本 mysql_get_server_info() 返回服务器的版本号 mysql_info() 返回关于最近所执行查询的信息 mysql_init() 获取或初始化 MYSQL 结构 mysql_insert_id() 返回上一个查询为 AUTO_INCREMENT 列生成的 ID mysql_kill() 杀死给定的线程 第 11 页

16 数字有机体工作库及大规模存储与管理系统开发手册 mysql_library_end() 最终确定 MySQL C API 库 mysql_library_init() 初始化 MySQL C API 库 mysql_list_dbs() 返回与简单正则表达式匹配的数据库名称 mysql_list_fields() 返回与简单正则表达式匹配的字段名称 mysql_list_processes() 返回当前服务器线程的列表 mysql_list_tables() 返回与简单正则表达式匹配的表名 mysql_more_results() 检查是否还存在其他结果 mysql_next_result() 在多语句执行过程中返回 / 初始化下一个结果 mysql_num_fields() 返回结果集中的列数 mysql_num_rows() 返回结果集中的行数 mysql_options() 为 mysql_connect() 设置连接选项 mysql_ping() 检查与服务器的连接是否工作, 如有必要重新连接 mysql_query() 执行指定为 以 Null 终结的字符串 的 SQL 查询 mysql_real_connect() 连接到 MySQL 服务器 mysql_real_escape_string() 考虑到连接的当前字符集, 为了在 SQL 语句中使用, 对字符串中的特殊字符进行转义处理 mysql_real_query() 执行指定为计数字符串的 SQL 查询 mysql_refresh() 刷新或复位表和高速缓冲 mysql_reload() 通知服务器再次加载授权表 mysql_rollback() 回滚事务 mysql_row_seek() 使用从 mysql_row_tell() 返回的值, 查找结果集中的行偏移 mysql_row_tell() 返回行光标位置 mysql_select_db() 选择数据库 mysql_server_end() 最终确定嵌入式服务器库 mysql_server_init() 初始化嵌入式服务器库 mysql_set_server_option() 为连接设置选项 ( 如多语句 ) mysql_sqlstate() 返回关于上一个错误的 SQLSTATE 错误代码 mysql_shutdown() 关闭数据库服务器 mysql_stat() 以字符串形式返回服务器状态 mysql_store_result() 检索完整的结果集至客户端 mysql_thread_id() 返回当前线程 ID mysql_thread_safe() 如果客户端已编译为线程安全的, 返回 1 mysql_use_result() 初始化逐行的结果集检索 mysql_warning_count() 返回上一个 SQL 语句的告警数 与数字有机体工作库交互时, 应用程序应使用以下一般性原则 : 第 12 页

17 成都天心悦高科技发展有限公司 1. 通过调用 mysql_library_init() 初始化接口库 2. 通过调用 mysql_init() 初始化连接处理句柄, 并通过调用 mysql_real_connect() 连接到服务器 3. 发出 SQL 语句并处理其结果 ( 在下面的讨论中, 详细介绍了使用它的方法 ) 4. 通过调用 mysql_close(), 关闭与 DosSQL 服务器的连接 5. 通过调用 mysql_library_end(), 结束接口库的使用 调用 mysql_library_init() 和 mysql_library_end() 的目的在于, 为接口库提供恰当的初始化和结束处理 对于与客户端库链接的应用程序, 它们提供了改进的内存管理功能 如果不调用 mysql_library_end(), 内存块仍将保持分配状态 ( 这不会增加应用程序使用的内存量, 但某些内存泄漏检测器将抗议它 ) 对于与嵌入式服务器链接的应用程序, 这些调用会启动并停止服务器 如果愿意, 可省略对 mysql_library_init() 的调用, 这是因为必要时 mysql_init() 会自动调用它 要想连接到服务器, 可调用 mysql_init() 来初始化连接处理句柄, 然后用该处理句柄 ( 以及其他信息, 如主机名 用户名和密码 ) 调用 mysql_real_connect() 建立连接后, mysql_real_connect() 会将再连接标志 (MYSQL 结构的一部分 ) 设置为 1 对于该标志, 值 1 指明, 如果因连接丢失而无法执行语句, 放弃之前, 会尝试再次连接到服务器 完成连接后, 退出程序前必须调用 mysql_close() 中止它 当连接处于活动状态时, 客户端或许会使用 mysql_query() 或 mysql_real_query() 向服务器发出 SQL 查询 两者的差别在于,mysql_query() 预期的查询为指定的 由 Null 终结的字符串, 而 mysql_real_query() 预期的是计数字符串 如果字符串包含二进制数据 ( 其中可能包含 Null 字节 ), 就必须使用 mysql_real_query() 对于每个非 SELECT 查询 ( 例如 INSERT UPDATE DELETE), 通过调用 mysql_affected_rows(), 可发现有多少行已被改变 ( 影响 ) 对于 SELECT 查询, 能够检索作为结果集的行 注意, 某些语句因其返回行类似于 SELECT, 包括 SHOW DESCRIBE 和 EXPLAIN, 应按照对待 SELECT 语句的方式处理它们 客户端处理结果集的方式有两种 一种方式是, 通过调用 mysql_store_result(), 一次性地检索整个结果集 该函数能从服务器获得查询返回的所有行, 并将它们保存在客户端 第二种方式是针对客户端的, 通过调用 mysql_use_result(), 对 按行 结果集检索进行初始化处理 该函数能初始化检索结果, 但不能从服务器获得任何实际行 在这两种情况下, 均能通过调用 mysql_fetch_row() 访问行 通过 mysql_store_result(), mysql_fetch_row() 能够访问以前从服务器获得的行 通过 mysql_use_result(), mysql_fetch_row() 能够实际地检索来自服务器的行 通过调用 mysql_fetch_lengths(), 能获得关于各行中数据大小的信息 完成结果集操作后, 请调用 mysql_free_result() 释放结果集使用的内存 这两种检索机制是互补的 客户端程序应选择最能满足其要求的方法 实际上, 客户端最常使用的是 mysql_store_result() 第 13 页

18 数字有机体工作库及大规模存储与管理系统开发手册 mysql_store_result() 的 1 个优点在于, 由于将行全部提取到了客户端上, 你不仅能连续访问行, 还能使用 mysql_data_seek() 或 mysql_row_seek() 在结果集中向前或向后移动, 以更改结果集内当前行的位置 通过调用 mysql_num_rows(), 还能发现有多少行 但另一方面, 对于大的结果集,mysql_store_result() 所需的内存可能会很大, 你很可能遇到内存溢出状况 mysql_use_result() 的 1 个优点在于, 客户端所需的用于结果集的内存较少 原因在于, 一次它仅维护一行 ( 由于分配开销较低,mysql_use_result() 能更快 ) 它的缺点在于, 你必须快速处理每一行以避免妨碍服务器, 你不能随机访问结果集中的行 ( 只能连续访问行 ), 你不知道结果集中有多少行, 直至全部检索了它们为止 不仅如此, 即使在检索过程中你判定已找到所寻找的信息, 也必须检索所有的行 通过 API, 客户端能够恰当地对查询作出响应 ( 仅在必要时检索行 ), 而无需知道查询是否是 SELECT 查询 可以在每次 mysql_query() 或 mysql_real_query() 后, 通过调用 mysql_store_result() 完成该操作 如果结果集调用成功, 查询为 SELECT, 而且能够读取行 如果结果集调用失败, 可调用 mysql_field_count() 来判断结果是否的确是所预期的 如果 mysql_field_count() 返回 0, 查询不返回数据 ( 表明它是 INSERT UPDATE DELETE 等 ), 而且不返回行 如果 mysql_field_count() 是非 0 值, 查询应返回行, 但没有返回行 这表明查询是失败了的 SELECT 关于如何实现该操作的示例, 请参见关于 mysql_field_count() 的介绍 无论是 mysql_store_result() 还是 mysql_use_result(), 均允许你获取关于构成结果集的字段的信息 ( 字段数目, 它们的名称和类型等 ) 通过重复调用 mysql_fetch_field(), 可以按顺序访问行内的字段信息 ; 或者通过调用 mysql_fetch_field_direct(), 能够在行内按字段编号访问字段信息 通过调用 mysql_field_seek(), 可以改变当前字段的光标位置 对字段光标的设置将影响后续的 mysql_fetch_field() 调用 此外, 你也能通过调用 mysql_fetch_fields(), 一次性地获得关于字段的所有信息 为了检测和通报错误,MySQL 提供了使用 mysql_errno() 和 mysql_error() 函数访问错误信息 它们能返回关于最近调用的函数的错误代码或错误消息 最近调用的函数可能成功也可能失败 这样, 你就能判断错误是在何时出现的, 以及错误是什么 C API 函数描述 在本节所作的介绍中, 按照 C 编程语言, 为 NULL 的参数或返回值表示 NULL, 而不是 MySQL Null 值 返回值的函数通常会返回指针或整数, 除非作了其他规定 返回指针的函数将返回非 NULL 值, 以指明成功, 或返回 NULL 值以指明出错 返回整数的函数将返回 0 以指明成功, 或返回非 0 值以指明出错 注意, 非 0 值仅表明这点, 除非在函数描述中作了其他说明. 不要对非 0 值进行测试 正确的方式是 if (result) /* correct */... error... 以下两种方式都是错误的 第 14 页

19 成都天心悦高科技发展有限公司 if (result < 0) /* incorrect */... error... if (result == -1) /* incorrect */... error... 当函数返回错误时, 在函数描述的 错误 部分将列出可能的错误类型 通过调用 mysql_errno() 可发现出现的错误是什么 通过调用 mysql_error(), 可获得错误的字符串表示 mysql_affected_rows() my_ulonglong mysql_affected_rows(mysql *mysql) 描述返回上次 UPDATE 更改的行数, 上次 DELETE 删除的行数, 或上次 INSERT 语句插入的行数 对于 UPDATE DELETE 或 INSERT 语句, 可在 mysql_query() 后立刻调用 对于 SELECT 语句,mysql_affected_rows() 的工作方式与 mysql_num_rows() 类似 返回值大于 0 的整数表明受影响或检索的行数 0 表示 UPDATE 语句未更新记录, 在查询中没有与 WHERE 匹配的行, 或未执行查询 -1 表示查询返回错误, 或者对于 SELECT 查询, 在调用 mysql_store_result() 之前调用了 mysql_affected_rows() 由于该函数返回无符号值, 可通过比较返回值和 (my_ulonglong)-1 检查是否为 -1 错误无 示例 : mysql_query(&mysql,"update products SET cost=cost*1.25 WHERE group=10"); printf("%ld products updated",(long) mysql_affected_rows(&mysql)); 如果在连接至 mysqld 时指定了标志 CLIENT_FOUND_ROWS, 对于 UPDATE 语句, mysql_affected_rows() 将返回 WHERE 语句匹配的行数 注意, 使用 REPLACE 命令时, 如果新行替代了旧行,mysql_affected_rows() 返回 2 这是因为, 在该情况下删除了重复行后插入了 1 行 如果使用 INSERT... ON DUPLICATE KEY UPDATE 来插入行, 如果行是作为新行插入的,mysql_affected_rows() 返回 1, 如果是更新了已有的行, 返回 mysql_autocommit() my_bool mysql_autocommit(mysql *mysql, my_bool mode) 描述如果模式为 1, 启用 autocommit 模式 ; 如果模式为 0, 禁止 autocommit 模式 返回值 第 15 页

20 数字有机体工作库及大规模存储与管理系统开发手册 如果成功, 返回 0, 如果出现错误, 返回非 0 值 错误无 mysql_change_user() my_bool mysql_change_user(mysql *mysql, const char *user, const char *password, const char *db) 描述更改用户, 并使由 db 指定的数据库成为由 mysql 指定的连接上的默认数据库 ( 当前数据库 ) 在后续查询中, 对于不包含显式数据库区分符的表引用, 该数据库是默认数据库 如果不能确定已连接的用户或用户不具有使用数据库的权限,mysql_change_user() 将失败 在这种情况下, 不会改变用户和数据库 如果不打算拥有默认数据库, 可将 db 参数设置为 NULL 该命令总是会执行活动事务的 ROLLBACK 操作, 关闭所有的临时表, 解锁所有的锁定表, 并复位状态, 就像进行了新连接那样 即使未更改用户, 也会出现该情况 返回值 0 表示成功, 非 0 值表示出现错误 错误与从 mysql_real_connect() 获得的相同 CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_SERVER_LOST 在查询过程中丢失了与服务器的连接 CR_UNKNOWN_ERROR 出现未知错误 ER_UNKNOWN_COM_ERROR MySQL 服务器未实施该命令 ( 或许是较低版本的服务器 ) ER_ACCESS_DENIED_ERROR 用户或密码错误 ER_BAD_DB_ERROR 数据库不存在 ER_DBACCESS_DENIED_ERROR 用户没有访问数据库的权限 ER_WRONG_DB_NAME 数据库名称过长 第 16 页

21 成都天心悦高科技发展有限公司 示例 : if (mysql_change_user(&mysql, "user", "password", "new_database")) fprintf(stderr, "Failed to change user. Error: %s\n", mysql_error(&mysql)); mysql_character_set_name() const char *mysql_character_set_name(mysql *mysql) 描述为当前连接返回默认的字符集 返回值默认字符集 错误无 mysql_close() void mysql_close(mysql *mysql) 描述关闭前面打开的连接 如果句柄是由 mysql_init() 或 mysql_connect() 自动分配的, mysql_close() 还将释放由 mysql 指向的连接句柄 返回值无 错误无 mysql_commit() my_bool mysql_commit(mysql *mysql) 描述提交当前事务 该函数的动作受 completion_type 系统变量的值控制 尤其是, 如果 completion_type 的值为 2, 终结事务并关闭客户端连接后, 服务器将执行释放操作 客户端程序应调用 mysql_close(), 从客户端一侧关闭连接 返回值如果成功, 返回 0, 如果出现错误, 返回非 0 值 错误 第 17 页

22 数字有机体工作库及大规模存储与管理系统开发手册 无 mysql_data_seek() void mysql_data_seek(mysql_res *result, my_ulonglong offset) 描述在查询结果集中寻找任意行 偏移值为行号, 范围从 0 到 mysql_num_rows(result)-1 该函数要求结果集结构包含查询的所有结果, 因此,so mysql_data_seek() 仅应与 mysql_store_result() 联合使用, 而不是与 mysql_use_result() 联合使用 返回值无 错误无 mysql_debug() void mysql_debug(const char *debug) 描述用给定的字符串执行 DBUG_PUSH mysql_debug() 采用 Fred Fish 调试库 要想使用该函数, 必须编译客户端库, 使之支持调试功能 返回值无 错误无 示例 : 这里给出的调用将使客户端库在客户端机器的 /tmp/client.trace 中生成 1 个跟踪文件 mysql_debug("d:t:o,/tmp/client.trace"); mysql_dump_debug_info() int mysql_dump_debug_info(mysql *mysql) 描述指示服务器将一些调试信息写入日志 要想使之工作, 已连接的用户必须具有 SUPER 权限 返回值如果命令成功, 返回 0 如果出现错误, 返回非 0 值 错误 CR_COMMANDS_OUT_OF_SYNC 第 18 页

23 成都天心悦高科技发展有限公司 以不恰当的顺序执行了命令 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_SERVER_LOST 在查询过程中, 与服务器的连接丢失 CR_UNKNOWN_ERROR 出现未知错误 mysql_errno() unsigned int mysql_errno(mysql *mysql) 描述对于由 mysql 指定的连接,mysql_errno() 返回最近调用的 API 函数的错误代码, 该函数调用可能成功也可能失败 0 返回值表示未出现错误 在 MySQL errmsg.h 头文件中, 列出了客户端错误消息编号 注意, 如果成功, 某些函数, 如 mysql_fetch_row() 等, 不会设置 mysql_errno() 经验规则是, 如果成功, 所有向服务器请求信息的函数均会复位 mysql_errno() 返回值如果失败, 返回上次 mysql_xxx() 调用的错误代码 0 表示未出现错误 错误无 mysql_error() const char *mysql_error(mysql *mysql) 描述对于由 mysql 指定的连接, 对于失败的最近调用的 API 函数,mysql_error() 返回包含错误消息的 由 Null 终结的字符串 如果该函数未失败,mysql_error() 的返回值可能是以前的错误, 或指明无错误的空字符串 经验规则是, 如果成功, 所有向服务器请求信息的函数均会复位 mysql_error() 对于复位 mysql_errno() 的函数, 下述两个测试是等效的 : if(mysql_errno(&mysql)) // an error occurred if(mysql_error(&mysql)[0]!= '\0') // an error occurred 第 19 页

24 数字有机体工作库及大规模存储与管理系统开发手册 通过重新编译 MySQL 客户端库, 可以更改客户端错误消息的语言 返回值返回描述错误的 由 Null 终结的字符串 如果未出现错误, 返回空字符串 错误无 mysql_fetch_field() MYSQL_FIELD *mysql_fetch_field(mysql_res *result) 描述返回采用 MYSQL_FIELD 结构的结果集的列 重复调用该函数, 以检索关于结果集中所有列的信息 未剩余字段时,mysql_fetch_field() 返回 NULL 每次执行新的 SELECT 查询时, 将复位 mysql_fetch_field(), 以返回关于第 1 个字段的信息 调用 mysql_field_seek() 也会影响 mysql_fetch_field() 返回的字段 如果调用了 mysql_query() 以在表上执行 SELECT, 但未调用 mysql_store_result(), 如果调用了 mysql_fetch_field() 以请求 BLOB 字段的长度,MySQL 将返回默认的 Blob 长度 (8KB) 之所以选择 8KB 是因为 MySQL 不知道 BLOB 的最大长度 应在日后使其成为可配置的 一旦检索了结果集,field->max_length 将包含特定查询中该列的最大值的长度 返回值当前列的 MYSQL_FIELD 结构 如果未剩余任何列, 返回 NULL 错误无 示例 : MYSQL_FIELD *field; while((field = mysql_fetch_field(result))) printf("field name %s\n", field->name); mysql_fetch_field_direct() MYSQL_FIELD *mysql_fetch_field_direct(mysql_res *result, unsigned int fieldnr) 描述给定结果集内某 1 列的字段编号 fieldnr, 以 MYSQL_FIELD 结构形式返回列的字段定义 可以使用该函数检索任意列的定义 Fieldnr 的值应在从 0 到 mysql_num_fields(result)-1 的范围内 返回值对于指定列, 返回 MYSQL_FIELD 结构 第 20 页

25 成都天心悦高科技发展有限公司 错误无 示例 : unsigned int num_fields; unsigned int i; MYSQL_FIELD *field; num_fields = mysql_num_fields(result); for(i = 0; i < num_fields; i++) field = mysql_fetch_field_direct(result, i); printf("field %u is %s\n", i, field->name); mysql_fetch_fields() MYSQL_FIELD *mysql_fetch_fields(mysql_res *result) 描述对于结果集, 返回所有 MYSQL_FIELD 结构的数组 每个结构提供了结果集中 1 列的字段定义 返回值关于结果集所有列的 MYSQL_FIELD 结构的数组 错误无 示例 : unsigned int num_fields; unsigned int i; MYSQL_FIELD *fields; num_fields = mysql_num_fields(result); fields = mysql_fetch_fields(result); for(i = 0; i < num_fields; i++) printf("field %u is %s\n", i, fields[i].name); mysql_fetch_lengths() 描述 unsigned long *mysql_fetch_lengths(mysql_res *result) 第 21 页

26 数字有机体工作库及大规模存储与管理系统开发手册 返回结果集内当前行的列的长度 如果打算复制字段值, 该长度信息有助于优化, 这是因为, 你能避免调用 strlen() 此外, 如果结果集包含二进制数据, 必须使用该函数来确定数据的大小, 原因在于, 对于包含 Null 字符的任何字段,strlen() 将返回错误的结果 对于空列以及包含 NULL 值的列, 其长度为 0 要想了解区分这两类情况的方法, 请参见关于 mysql_fetch_row() 的介绍 返回值无符号长整数的数组表示各列的大小 ( 不包括任何终结 NULL 字符 ) 如果出现错误, 返回 NULL 错误 mysql_fetch_lengths() 仅对结果集的当前行有效 如果在调用 mysql_fetch_row() 之前或检索了结果集中的所有行后调用了它, 将返回 NULL 示例 : MYSQL_ROW row; unsigned long *lengths; unsigned int num_fields; unsigned int i; row = mysql_fetch_row(result); if (row) num_fields = mysql_num_fields(result); lengths = mysql_fetch_lengths(result); for(i = 0; i < num_fields; i++) printf("column %u is %lu bytes in length.\n", i, lengths[i]); mysql_fetch_row() MYSQL_ROW mysql_fetch_row(mysql_res *result) 描述检索结果集的下一行 在 mysql_store_result() 之后使用时, 如果没有要检索的行, mysql_fetch_row() 返回 NULL 在 mysql_use_result() 之后使用时, 如果没有要检索的行或出现了错误,mysql_fetch_row() 返回 NULL 行内值的数目由 mysql_num_fields(result) 给出 如果行中保存了调用 mysql_fetch_row() 返回的值, 将按照 row[0] 到 row[mysql_num_fields(result)-1], 访问这些值的指针 行中的 NULL 值由 NULL 指针指明 第 22 页

27 成都天心悦高科技发展有限公司 可以通过调用 mysql_fetch_lengths() 来获得行中字段值的长度 对于空字段以及包含 NULL 的字段, 长度为 0 通过检查字段值的指针, 能够区分它们 如果指针为 NULL, 字段为 NULL, 否则字段为空 返回值下一行的 MYSQL_ROW 结构 如果没有更多要检索的行或出现了错误, 返回 NULL 错误注意, 在对 mysql_fetch_row() 的两次调用之间, 不会复位错误 CR_SERVER_LOST 在查询过程中, 与服务器的连接丢失 CR_UNKNOWN_ERROR 出现未知错误 示例 : MYSQL_ROW row; unsigned int num_fields; unsigned int i; num_fields = mysql_num_fields(result); while ((row = mysql_fetch_row(result))) unsigned long *lengths; lengths = mysql_fetch_lengths(result); for(i = 0; i < num_fields; i++) printf("[%.*s] ", (int) lengths[i], row[i]? row[i] : "NULL"); printf("\n"); mysql_field_count() unsigned int mysql_field_count(mysql *mysql) 描述返回作用在连接上的最近查询的列数 该函数的正常使用是在 mysql_store_result() 返回 NULL( 因而没有结果集指针 ) 时 在这种情况下, 可调用 mysql_field_count() 来判定 mysql_store_result() 是否应生成非空结果 这样, 客户端就能采取恰当的动作, 而无需知道查询是否是 SELECT( 或类似 SELECT 的 ) 语句 在这里给出的示例中, 演示了完成它的方法 返回值表示结果集中列数的无符号整数 错误第 23 页

28 数字有机体工作库及大规模存储与管理系统开发手册 无 示例 : MYSQL_RES *result; unsigned int num_fields; unsigned int num_rows; if (mysql_query(&mysql,query_string)) // error else // query succeeded, process any data returned by it result = mysql_store_result(&mysql); if (result) // there are rows num_fields = mysql_num_fields(result); // retrieve rows, then call mysql_free_result(result) else // mysql_store_result() returned nothing; should it have? if(mysql_field_count(&mysql) == 0) // query does not return data // (it was not a SELECT) num_rows = mysql_affected_rows(&mysql); else // mysql_store_result() should have returned data fprintf(stderr, "Error: %s\n", mysql_error(&mysql)); 另一种可选的方法是, 用 mysql_errno(&mysql) 替换 mysql_field_count(&mysql) 调用 在该情况下, 无论语句是否是 SELECT, 你将直接从 mysql_store_result() 查找错误, 而不是从 mysql_field_count() 的值进行推断 mysql_field_seek() MYSQL_FIELD_OFFSET mysql_field_seek(mysql_res *result, MYSQL_FIELD_OFFSET offset) 描述将字段光标设置到给定的偏移处 对 mysql_fetch_field() 的下一次调用将检索与该偏移相关的列定义 第 24 页

29 成都天心悦高科技发展有限公司 要想查找行的开始, 请传递值为 0 的偏移量 返回值字段光标的前一个值 错误无 mysql_field_tell() MYSQL_FIELD_OFFSET mysql_field_tell(mysql_res *result) 描述返回上一个 mysql_fetch_field() 所使用的字段光标的定义 该值可用作 mysql_field_seek() 的参量 返回值字段光标的当前偏移量 错误无 mysql_free_result() void mysql_free_result(mysql_res *result) 描述释放由 mysql_store_result() mysql_use_result() mysql_list_dbs() 等为结果集分配的内存 完成对结果集的操作后, 必须调用 mysql_free_result() 释放结果集使用的内存 释放完成后, 不要尝试访问结果集 返回值无 错误无 mysql_get_character_set_info() void mysql_get_character_set_info(mysql *mysql, MY_CHARSET_INFO *cs) 描述该函数提供了关于默认客户端字符集的信息 可以使用 mysql_set_character_set() 函数更改默认的字符集 示例 : if (!mysql_set_character_set(&mysql, "utf8")) MY_CHARSET_INFO cs; 第 25 页

30 数字有机体工作库及大规模存储与管理系统开发手册 mysql_get_character_set_info(&mysql, &cs); printf("character set information:\n"); printf("character set name: %s\n", cs.name); printf("collation name: %s\n", cs.csname); printf("comment: %s\n", cs.comment); printf("directory: %s\n", cs.dir); printf("multi byte character min. length: %d\n", cs.mbminlen); printf("multi byte character max. length: %d\n", cs.mbmaxlen); mysql_get_host_info() char *mysql_get_host_info(mysql *mysql) 描述返回描述了所使用连接类型的字符串, 包括服务器主机名 返回值代表服务器主机名和连接类型的字符串 错误无 mysql_get_proto_info() unsigned int mysql_get_proto_info(mysql *mysql) 描述返回当前连接所使用的协议版本 返回值代表当前连接所使用协议版本的无符号整数 错误无 mysql_get_server_info() char *mysql_get_server_info(mysql *mysql) 描述返回代表服务器版本号的字符串 返回值代表服务器版本号的字符串 错误无 第 26 页

31 成都天心悦高科技发展有限公司 mysql_get_server_version() unsigned long mysql_get_server_version(mysql *mysql) 描述以整数形式返回服务器的版本号 返回值表示 MySQL 服务器版本的数值, 格式如下 : major_version* minor_version *100 + sub_version 例如, 对于 , 返回 在客户端程序中, 为了快速确定某些与版本相关的服务器功能是否存在, 该函数很有用 错误无 mysql_hex_string() unsigned long mysql_hex_string(char *to, const char *from, unsigned long length) 描述该函数用于创建可用在 SQL 语句中的合法 SQL 字符串 该字符串从形式上编码为十六进制格式, 每个字符编码为 2 个十六进制数 结果被置入其中, 并添加 1 个终结 Null 字节 from 所指向的字符串必须是长度字节 long 必须为 to 分配缓冲区, 缓冲区至少为 length*2+1 字节长 当 mysql_hex_string() 返回时, to 的内容为由 Null 终结的字符串 返回值是编码字符串的长度, 不包括终结用 Null 字符 可采用 0xvalue 或 X'value' 格式将返回值置于 SQL 语句中 但是, 返回值不包括 0x 或 X'...' 调用者必须提供所希望的格式是何种 示例 : char query[1000],*end; end = strmov(query,"insert INTO test_table values("); end = strmov(end,"0x"); end += mysql_hex_string(end,"what's this",11); end = strmov(end,",0x"); end += mysql_hex_string(end,"binary data: \0\r\n",16); *end++ = ')'; if (mysql_real_query(&mysql,query,(unsigned int) (end - query))) fprintf(stderr, "Failed to insert row, Error: %s\n", mysql_error(&mysql)); 第 27 页

32 数字有机体工作库及大规模存储与管理系统开发手册 示例中所使用的 strmov() 函数包含在 mysqlclient 库中, 它的工作方式类似于 strcpy(), 但返回指向第 1 个参数终结 Null 的指针 返回值置于 to 中的值的长度, 不包括终结用 Null 字符 错误无 mysql_info() char *mysql_info(mysql *mysql) 描述检索字符串, 该字符串提供了关于最近执行查询的信息, 但仅对这里列出的语句有效 对于其他语句,mysql_info() 返回 NULL 字符串的格式取决于查询的类型, 如本节所述 数值仅是说明性的, 字符串包含与查询相适应的值 INSERT INTO... SELECT... 字符串格式 : 记录,100; 副本,0; 警告,0 INSERT INTO... VALUES (...),(...),(...)... 字符串格式 : 记录,3; 副本,0; 警告,0 LOAD DATA INFILE... 字符串格式 : 记录,1; 删除,0; 跳过,0; 警告,0 ALTER TABLE 字符串格式 : 记录,3; 副本,0; 警告,0 UPDATE 字符串格式 : 匹配行,40; 更改,40; 警告,0 注意,mysql_info() 为 INSERT... VALUES 返回非 NULL 值,INSERT... VALUES 仅用于多行形式的语句 ( 也就是说, 仅当指定了多个值列表时 ) 返回值字符串, 它表示最近所执行查询的额外信息 如果该查询无可用信息, 返回 NULL 错误无 mysql_init() MYSQL *mysql_init(mysql *mysql) 描述分配或初始化与 mysql_real_connect() 相适应的 MYSQL 对象 如果 mysql 是 NULL 指针, 该函数将分配 初始化 并返回新对象 否则, 将初始化对象, 并返回对象的地址 如果 mysql_init() 分配了新的对象, 当调用 mysql_close() 来关闭连接时 将释放该对象 第 28 页

33 成都天心悦高科技发展有限公司 返回值初始化的 MYSQL* 句柄 如果无足够内存以分配新的对象, 返回 NULL 错误在内存不足的情况下, 返回 NULL mysql_insert_id() my_ulonglong mysql_insert_id(mysql *mysql) 描述返回由以前的 INSERT 或 UPDATE 语句为 AUTO_INCREMENT 列生成的值 在包含 AUTO_INCREMENT 字段的表中执行了 INSERT 语句后, 应使用该函数 更准确地讲, 将在下述条件下更新 mysql_insert_id(): 将值保存到 AUTO_INCREMENT 列中的 INSERT 语句 无论值是通过在列中存储特殊值 NULL 或 0 自动生成的, 还是确切的非特殊值, 都成立 在有多行 INSERT 语句的情况下,mysql_insert_id() 返回第 1 个自动生成的 AUTO_INCREMENT 值, 如果未生成这类值, 将返回插入在 AUTO_INCREMENT 列中的最后 1 个确切值 通过将 LAST_INSERT_ID(expr) 插入到任意列中以生成 AUTO_INCREMENT 值的 INSERT 语句 通过更新任意列至 LAST_INSERT_ID(expr) 以生成 AUTO_INCREMENT 值的 INSERT 语句 mysql_insert_id() 的值不受诸如 SELECT 等返回结果集的语句的影响 如果前面的语句返回了错误,mysql_insert_id() 的值将是不确定的 注意, 如果前面的语句未使用 AUTO_INCREMENT,mysql_insert_id() 返回 0 如果需要保存值, 在生成值的语句后, 务必立刻调用 mysql_insert_id() mysql_insert_id() 的值仅受在当前客户端连接内发出的语句的影响 不受由其他客户端发出的语句的影响 此外还应注意,SQL LAST_INSERT_ID() 函数的值总包含最近生成的 AUTO_INCREMENT 值, 而且在语句之间不会被复位, 原因在于该函数的值是在服务器中维护的 另一个区别是, 如果设置了 AUTO_INCREMENT 列来指定非特殊值, 不会更新 LAST_INSERT_ID() LAST_INSERT_ID() 不同于 mysql_insert_id() 的原因在于,LAST_INSERT_ID() 在脚本中很容易使用, 而 mysql_insert_id() 则试图提供关于在 AUTO_INCREMENT 列中出现情况的更准确信息 返回值在前面的讨论中已予以了介绍 错误无 第 29 页

34 数字有机体工作库及大规模存储与管理系统开发手册 mysql_kill() int mysql_kill(mysql *mysql, unsigned long pid) 描述请求服务器杀死由 pid 指定的线程 返回值 0 表示成功, 非 0 值表示出现错误 错误 CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_SERVER_LOST 在查询过程中, 与服务器的连接丢失 CR_UNKNOWN_ERROR 出现未知错误 mysql_library_end() void mysql_library_end(void) 描述它是 mysql_server_end() 函数的同义词 mysql_library_init() int mysql_library_init(int argc, char **argv, char **groups) 描述这是 mysql_server_init() 函数的同义词 mysql_list_dbs() MYSQL_RES *mysql_list_dbs(mysql *mysql, const char *wild) 描述返回由服务器上的数据库名称组成的结果集, 该服务器与由通配符参数指定的简单正则表达式匹配 通配符参数可以包含通配符 % 或 _, 也可以是 NULL 指针, 以便与所有的数据库匹配 调用 mysql_list_dbs() 的方法类似于执行查询 SHOW database [LIKE wild] 必须用 mysql_free_result() 释放结果集 返回值成功后返回 MYSQL_RES 结果集 如果出现错误, 返回 NULL 第 30 页

35 成都天心悦高科技发展有限公司 错误 CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令 CR_OUT_OF_MEMORY 内存溢出 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_SERVER_LOST 在查询过程中, 与服务器的连接丢失 CR_UNKNOWN_ERROR 出现未知错误 mysql_list_fields() MYSQL_RES *mysql_list_fields(mysql *mysql, const char *table, const char *wild) 描述返回由给定表中的字段名称组成的结果集, 给定表与由通配符参数指定的简单正则表达式匹配 通配符参数可以包含通配符 % 或 _, 也可以是 NULL 指针, 以便与所有的字段匹配 调用 mysql_list_fields() 的方法类似于执行查询 SHOW COLUMNS FROM tbl_name [LIKE wild] 注意, 建议使用 SHOW COLUMNS FROM tbl_name, 而不是 mysql_list_fields() 必须用 mysql_free_result() 释放结果集 返回值如果成功, 返回 MYSQL_RES 结果集 如果出现错误, 返回 NULL 错误 CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_SERVER_LOST 在查询过程中, 与服务器的连接丢失 CR_UNKNOWN_ERROR 出现未知错误 mysql_list_processes() 描述 MYSQL_RES *mysql_list_processes(mysql *mysql) 第 31 页

36 数字有机体工作库及大规模存储与管理系统开发手册 返回描述当前服务器线程的结果集 该类信息与 mysqladmin processlist 或 SHOW PROCESSLIST 查询给出的信息相同 必须用 mysql_free_result() 释放结果集 返回值如果成功, 返回 MYSQL_RES 结果集 如果出现错误, 返回 NULL 错误 CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_SERVER_LOST 在查询过程中, 与服务器的连接丢失 CR_UNKNOWN_ERROR 出现未知错误 mysql_list_tables() MYSQL_RES *mysql_list_tables(mysql *mysql, const char *wild) 描述返回由当前数据库内的表名组成的结果集, 当前数据库与由通配符参数指定的简单正则表达式匹配 通配符参数可以包含通配符 % 或 _, 也可以是 NULL 指针, 以便与所有的表匹配 调用 mysql_list_tables() 的方法类似于执行查询 HOW tables [LIKE wild] 必须用 mysql_free_result() 释放结果集 返回值如果成功, 返回 MYSQL_RES 结果集 如果出现错误, 返回 NULL 错误 CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_SERVER_LOST 在查询过程中, 与服务器的连接丢失 CR_UNKNOWN_ERROR 出现未知错误 mysql_more_results() 描述 my_bool mysql_more_results(mysql *mysql) 第 32 页

37 成都天心悦高科技发展有限公司 如果当前执行的查询存在多个结果, 返回 真, 而且应用程序必须调用 mysql_next_result() 来获取结果 返回值如果存在多个结果, 返回 真 (1), 如果不存在多个结果, 返回 假 (0) 在大多数情况下, 可调用 mysql_next_result() 来测试是否存在多个结果, 如果存在多个结果, 对检索进行初始化操作 错误无 mysql_next_result() int mysql_next_result(mysql *mysql) 描述如果存在多个查询结果,mysql_next_result() 将读取下一个查询结果, 并将状态返回给应用程序 如果前面的查询返回了结果集, 必须为其调用 mysql_free_result() 调用了 mysql_next_result() 后, 连接状态就像你已为下一查询调用了 mysql_real_query() 或 mysql_query() 时的一样 这意味着你能调用 mysql_store_result() mysql_warning_count() mysql_affected_rows() 等等 如果 mysql_next_result() 返回错误, 将不执行任何其他语句, 也不会获取任何更多的结果返回值返回值描述 0 成功并有多个结果 -1 成功但没有多个结果 >0 出错错误 CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令 例如, 没有为前面的结果集调用 mysql_use_result() CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_SERVER_LOST 在查询过程中, 与服务器的连接丢失 CR_UNKNOWN_ERROR 出现未知错误 mysql_num_fields() unsigned int mysql_num_fields(mysql_res *result) 第 33 页

38 数字有机体工作库及大规模存储与管理系统开发手册 要想传递 MYSQL* 参量取而代之, 请使用无符号整数 mysql_field_count(mysql *mysql) 描述返回结果集中的行数 注意, 你可以从指向结果集的指针或指向连接句柄的指针获得行数 如果 mysql_store_result() 或 mysql_use_result() 返回 NULL, 应使用连接句柄 ( 因而没有结果集指针 ) 在该情况下, 可调用 mysql_field_count() 来判断 mysql_store_result() 是否生成了非空结果 这样, 客户端程序就能采取恰当的行动, 而不需要知道查询是否是 SELECT 语句 ( 或类似 SELECT 的语句 ) 在下面的示例中, 介绍了执行该操作的方式 返回值表示结果集中行数的无符号整数 错误无 示例 : MYSQL_RES *result; unsigned int num_fields; unsigned int num_rows; if (mysql_query(&mysql,query_string)) // error else // query succeeded, process any data returned by it result = mysql_store_result(&mysql); if (result) // there are rows num_fields = mysql_num_fields(result); // retrieve rows, then call mysql_free_result(result) else // mysql_store_result() returned nothing; should it have? if (mysql_errno(&mysql)) fprintf(stderr, "Error: %s\n", mysql_error(&mysql)); else if (mysql_field_count(&mysql) == 0) // query does not return data // (it was not a SELECT) num_rows = mysql_affected_rows(&mysql); 第 34 页

39 成都天心悦高科技发展有限公司 另一种可选方式是 ( 如果你知道你的查询应返回结果集 ), 使用检查 mysql_field_count(&mysql) is = 0 来替换 mysql_errno(&mysql) 调用 仅当出错时才应使用它 mysql_num_rows() my_ulonglong mysql_num_rows(mysql_res *result) 描述返回结果集中的行数 mysql_num_rows() 的使用取决于是否采用了 mysql_store_result() 或 mysql_use_result() 来返回结果集 如果使用了 mysql_store_result(), 可以立刻调用 mysql_num_rows() 如果使用了 mysql_use_result(),mysql_num_rows() 不返回正确的值, 直至检索了结果集中的所有行为止 返回值结果集中的行数 错误无 mysql_options() int mysql_options(mysql *mysql, enum mysql_option option, const char *arg) 描述可用于设置额外的连接选项, 并影响连接的行为 可多次调用该函数来设置数个选项 应在 mysql_init() 之后 以及 mysql_connect() 或 mysql_real_connect() 之前调用 mysql_options() 选项参量指的是你打算设置的选项 Arg 参量是选项的值 如果选项是整数, 那么 arg 应指向整数的值 可能的选项值 : 选项参量类型功能 MYSQL_INIT_COMMAN 连接到 MySQL 服务器时将执行的命令, 再次连 char * D 接时将自动地再次执行 MYSQL_OPT_COMPRESS 未使用使用压缩客户端 / 服务器协议 MYSQL_OPT_CONNECT_ unsigned int 以秒为单位的连接超时 TIMEOUT * 第 35 页

40 数字有机体工作库及大规模存储与管理系统开发手册 对于与 libmysqld 链接的应用程序, 允许库 猜 测 是否使用嵌入式服务器或远程服务器 猜 测 表示, 如果设置了主机名但不是本地主机, MYSQL_OPT_GUESS_CO 将使用远程服务器 该行为是默认行为 可使未使用 NNECTION 用 MYSQL_OPT_USE_EMBEDDED_CONNEC TION 和 MYSQL_OPT_USE_REMOTE_CON NECTION 覆盖它 对于与 libmysqlclient 链接 的应用程序, 该选项将被忽略 MYSQL_OPT_LOCAL_IN FILE 指向单元的可选指针 如果未给定指针, 或指针指向 unsigned int!= 0, 将允许命令 LOAD LOCAL INFILE MYSQL_OPT_NAMED_PI 使用命名管道连接到 NT 平台上的 MySQL 服务未使用 PE 器 MYSQL_OPT_PROTOCO L unsigned int * 要使用的协议类型 应是 mysql.h 中定义的 my sql_protocol_type 的枚举值之一 MYSQL_OPT_READ_TIM EOUT unsigned int * 从服务器读取信息的超时 ( 目前仅在 Windows 平台的 TCP/IP 连接上有效 ) MYSQL_OPT_RECONNE 如果发现连接丢失, 启动或禁止与服务器的自 my_bool * CT 动再连接 对于与 libmysqld 链接的应用程序 ( 具备鉴定支 持特性的已编译 libmysqld), 它意味着, 出于 MYSQL_OPT_SET_CLIEN char * 鉴定目的, 用户将被视为从指定的 IP 地址 ( 指 T_IP 定为字符串 ) 进行连接 对于与 libmysqlclient 链接的应用程序, 该选项将被忽略 未使用对于与 libmysqld 链接的应用程序, 就连接而 MYSQL_OPT_USE_EMBE 言, 它将强制使用嵌入式服务器 对于与 libm DDED_CONNECTION ysqlclient 链接的应用程序, 该选项将被忽略 未使用对于与 libmysqld 链接的应用程序, 就连接而 MYSQL_OPT_USE_REM 言, 它将强制使用远程服务器 对于与 libmys OTE_CONNECTION qlclient 链接的应用程序, 该选项将被忽略 MYSQL_OPT_USE_RESU LT 未使用 不使用该选项 MYSQL_OPT_WRITE_TI MEOUT unsigned int * 写入服务器的超时 ( 目前仅在 Windows 平台的 TCP/IP 连接上有效 ) MYSQL_READ_DEFAUL T_FILE char * 从命名选项文件而不是从 my.cnf 读取选项 MYSQL_READ_DEFAUL 从 my.cnf 或用 MYSQL_READ_DEFAULT_FIL char * T_GROUP E 指定的文件中的命名组读取选项 MYSQL_REPORT_DATA_ 通过 MYSQL_BIND.error, 对于预处理语句, my_bool * TRUNCATION 允许或禁止通报数据截断错误 ( 默认为禁止 ) MYSQL_SECURE_AUTH my_bool* 是否连接到不支持密码混编功能的服务器 MYSQL_SET_CHARSET_ DIR char* 指向包含字符集定义文件的目录的路径名 MYSQL_SET_CHARSET_ NAME char* 用作默认字符集的字符集的名称 第 36 页

41 成都天心悦高科技发展有限公司 MYSQL_SHARED_MEMO RY_BASE_NAME char* 命名为与服务器进行通信的共享内存对象 应 与你打算连接的 mysqld 服务器使用的选项 -sh ared-memory-base-name 相同 注意, 如果使用了 MYSQL_READ_DEFAULT_FILE 或 MYSQL_READ_DEFAULT_G ROUP, 总会读取客户端组 选项文件中指定的组可能包含下述选项 : 选项 connect-timeout compress database debug 描述 以秒为单位的连接超时 在 Linux 平台上, 该超时也 用作等待服务器首次回应的时间 使用压缩客户端 / 服务器协议 如果在连接命令中未指定数据库, 连接到该数据库 调试选项 disable-local-infile 禁止使用 LOAD DATA LOCAL host init-command interactive-timeout local-infile[=(0 1)] max_allowed_packet multi-results multi-statements password pipe 默认主机名 连接到 MySQL 服务器时将执行的命令, 再次连接时 将自动地再次执行 等同于将 CLIENT_INTERACTIVE 指定为 mysql_real_connect() 如果无参量或参量!= 0, 那么将允许使用 LOAD DATA LOCAL 客户端能够从服务器读取的最大信息包 允许多语句执行或存储程序的多个结果集 允许客户端在 1 个字符串内发送多条语句 ( 由 ; 隔开 ) 默认密码 使用命名管道连接到 NT 平台上的 MySQL 服务器 protocol=tcp SOCKET PIPE MEMORY port return-found-rows shared-memory-base-name=name socket user 连接到服务器时将使用的协议 默认端口号 通知 mysql_info() 返回发现的行, 而不是使用 UPDATE 时更新的行 共享内存名称, 用于连接到服务器 ( 默认为 "MYSQL") 默认的套接字文件 默认用户 注意, timeout ( 超时 ) 已被 connect-timeout ( 连接超时 ) 取代 返回值成功时返回 0 如果使用了未知选项, 返回非 0 值 示例 : MYSQL mysql; 第 37 页

42 数字有机体工作库及大规模存储与管理系统开发手册 mysql_init(&mysql); mysql_options(&mysql,mysql_opt_compress,0); mysql_options(&mysql,mysql_read_default_group,"odbc"); if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,null,0)) fprintf(stderr, "Failed to connect to database: Error: %s\n", mysql_error(&mysql)); 该代码请求客户端使用压缩客户端 / 服务器协议, 并从 my.cnf 文件的 obdc 部分读取额外选项 mysql_ping() int mysql_ping(mysql *mysql) 描述检查与服务器的连接是否工作 如果连接丢失, 将自动尝试再连接 该函数可被闲置了较长时间的客户端使用, 用以检查服务器是否已关闭了连接, 并在必要时再次连接 返回值如果与服务器的连接有效返回 0 如果出现错误, 返回非 0 值 返回的非 0 值不表示 MySQL 服务器本身是否已关闭, 连接失效可能有其他原因, 如网络故障等 错误 CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_UNKNOWN_ERROR 出现未知错误 mysql_query() int mysql_query(mysql *mysql, const char *query) 描述执行由 Null 终结的字符串 查询指向的 SQL 查询 正常情况下, 字符串必须包含 1 条 SQL 语句, 而且不应为语句添加终结分号 ( ; ) 或 \g 如果允许多语句执行, 字符串可包含多条由分号隔开的语句 mysql_query() 不能用于包含二进制数据的查询, 应使用 mysql_real_query() 取而代之 ( 二进制数据可能包含字符 \0,mysql_query() 会将该字符解释为查询字符串结束 ) 如果希望了解查询是否应返回结果集, 可使用 mysql_field_count() 进行检查 返回值 第 38 页

43 成都天心悦高科技发展有限公司 如果查询成功, 返回 0 如果出现错误, 返回非 0 值 错误 CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_SERVER_LOST 在查询过程中, 与服务器的连接丢失 CR_UNKNOWN_ERROR 出现未知错误 mysql_real_connect() MYSQL *mysql_real_connect(mysql *mysql, const char *host, const char *user, const char *passwd, const char *db, unsigned int port, const char *unix_socket, unsigned long client_flag) 描述 mysql_real_connect() 尝试与运行在主机上的 MySQL 数据库引擎建立连接 在你能够执行需要有效 MySQL 连接句柄结构的任何其他 API 函数之前,mysql_real_connect() 必须成功完成 参数的指定方式如下 : 第 1 个参数应是已有 MYSQL 结构的地址 调用 mysql_real_connect() 之前, 必须调用 mysql_init() 来初始化 MYSQL 结构 通过 mysql_options() 调用, 可更改多种连接选项 host 的值必须是主机名或 IP 地址 如果 host 是 NULL 或字符串 "localhost", 其连接将被视为与本地主机的连接 如果操作系统支持套接字 (Unix) 或命名管道 (Windows), 将使用它们而不是 TCP/IP 连接到服务器 user 参数包含用户的 DosSQL 登录 ID 如果 user 是 NULL 或空字符串 "", 用户将被视为当前用户 在 UNIX 环境下, 它是当前的登录名 在 Windows ODBC 下, 必须明确指定当前用户名 passwd 参数包含用户的密码 如果 passwd 是 NULL, 仅会对该用户的 ( 拥有 1 个空密码字段的 ) 用户表中的条目进行匹配检查 这样, 数据库管理员就能按特定的方式设置 DosSQL 权限系统, 根据用户是否拥有指定的密码, 用户将获得不同的权限 注释 : 调用 mysql_real_connect() 之前, 不要尝试加密密码, 密码加密将由客户端 API 自动处理 db 是数据库名称 如果 db 为 NULL, 连接会将默认的数据库设为该值 如果 port 不是 0, 其值将用作 TCP/IP 连接的端口号 注意, host 参数决定了连接的类型 如果 unix_socket 不是 NULL, 该字符串描述了应使用的套接字或命名管道 注意, host 参数决定了连接的类型 第 39 页

44 数字有机体工作库及大规模存储与管理系统开发手册 client_flag 的值通常为 0, 但是也能将其设置为下述标志的组合, 以允许特定功能 : 标志名称标志描述 CLIENT_COMPRESS 使用压缩协议 CLIENT_FOUND_ROWS CLIENT_IGNORE_SPACE CLIENT_INTERACTIVE CLIENT_LOCAL_FILES CLIENT_MULTI_STATEMENTS CLIENT_MULTI_RESULTS CLIENT_NO_SCHEMA CLIENT_ODBC CLIENT_SSL 返回发现的行数 ( 匹配的 ), 而不是受影响的行数 允许在函数名后使用空格, 使所有的函数名成为保留字 关闭连接之前, 允许 interactive_timeout( 取代了 wait_timeout) 秒的不活动时间 客户端的会话 wait_timeout 变量被设为会话 interactive_timeout 变量的值 允许 LOAD DATA LOCAL 处理功能 通知服务器, 客户端可能在单个字符串内发送多条语句 ( 由 ; 隔开 ) 如果未设置该标志, 将禁止多语句执行 通知服务器, 客户端能够处理来自多语句执行或存储程序的多个结果集 如果设置了 CLIENT_MULTI_STATEMENTS, 将自动设置它 禁止 db_name.tbl_name.col_name 语法 它用于 ODBC 如果使用了该语法, 它会使分析程序生成错误, 在捕获某些 ODBC 程序中的缺陷时, 它很有用 客户端是 ODBC 客户端, 它将 mysqld 变得更为 ODBC 友好 使用 SSL( 加密协议 ) 该选项不应由应用程序设置, 它是在客户端库内部设置的 对于某些参数, 能够从选项文件获得取值, 而不是取得 mysql_real_connect() 调用中的确切值 为此, 在调用 mysql_real_connect() 之前, 应与 MYSQL_READ_DEFAULT_FILE 或 MYSQL_READ_DEFAULT_GROUP 选项一起调用 mysql_options() 随后, 在 mysql_real_connect() 调用中, 为准备从选项文件读取值的每个参数指定 无值 值 : 对于 host, 指定 NULL 值或空字符串 ("") 对于 user, 指定 NULL 值或空字符串 对于 passwd, 指定 NULL 值 ( 对于密码,mysql_real_connect() 调用中的空字符串的值不能被选项文件中的字符串覆盖, 这是因为空字符串明确指明 MySQL 账户必须有空密码 ) 对于 db, 指定 NULL 值或空字符串 对于 port, 指定 0 值 对于 unix_socket, 指定 NULL 值 对于某一参数, 如果在选项文件中未发现值, 将使用它的默认值, 如本节前面介绍的那样 返回值 第 40 页

45 成都天心悦高科技发展有限公司 如果连接成功, 返回 MYSQL* 连接句柄 如果连接失败, 返回 NULL 对于成功的连接, 返回值与第 1 个参数的值相同 错误 CR_CONN_HOST_ERROR 无法连接到 MySQL 服务器 CR_CONNECTION_ERROR 无法连接到本地 MySQL 服务器 CR_IPSOCK_ERROR 无法创建 IP 套接字 CR_OUT_OF_MEMORY 内存溢出 CR_SOCKET_CREATE_ERROR 无法创建 Unix 套接字 CR_UNKNOWN_HOST 无法找到主机名的 IP 地址 CR_VERSION_ERROR 协议不匹配, 起因于试图连接到具有特定客户端库 ( 该客户端库使用了不同的协议版本 ) 的服务器 如果使用很早的客户端库来建立与较新的服务器 ( 未使用 --old-protocol 选项开始的 ) 的连接, 就会出现该情况 CR_NAMEDPIPEOPEN_ERROR 无法在 Windows 平台下创建命名管道 CR_NAMEDPIPEWAIT_ERROR 在 Windows 平台下等待命名管道失败 CR_NAMEDPIPESETSTATE_ERROR 在 Windows 平台下获取管道处理程序失败 CR_SERVER_LOST 如果 connect_timeout > 0, 而且在连接服务器时所用时间长于 connect_timeout 秒, 或在执行 init-command 时服务器消失 示例 : MYSQL mysql; mysql_init(&mysql); mysql_options(&mysql,mysql_read_default_group,"your_prog_name"); if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,null,0)) fprintf(stderr, "Failed to connect to database: Error: %s\n", mysql_error(&mysql)); 第 41 页

46 数字有机体工作库及大规模存储与管理系统开发手册 通过使用 mysql_options(), 接口库将读取 my.cnf 文件的 [client] 和 [your_prog_name] 部分, 以确保程序工作, 即使某人以某种非标准的方式设置 DosSQL 也同样 注意, 一旦建立了连接,mysql_real_connect() 将设置再连接标志 (MYSQL 结构的组成部份 ) 的值 值 1 表示, 如果因连接丢失而无法执行语句, 放弃前将尝试再次连接到服务器 mysql_real_escape_string() unsigned long mysql_real_escape_string(mysql *mysql, char *to, const char *from, unsigned long length) 注意,mysql 必须是有效的开放式连接 之所以需要它是因为, 转义功能取决于服务器使用的字符集 描述该函数用于创建可在 SQL 语句中使用的合法 SQL 字符串 按照连接的当前字符集, 将 from 中的字符串编码为转义 SQL 字符串 将结果置于 to 中, 并添加 1 个终结用 NULL 字节 编码的字符为 NUL (ASCII 0) \n \r \ ' " 以及 Control-Z ( 严格地讲,MySQL 仅需要反斜杠和引号字符, 用于引用转义查询中的字符串 该函数能引用其他字符, 从而使得它们在日志文件中具有更好的可读性 ) from 指向的字符串必须是长度字节 long 必须为 to 缓冲区分配至少 length*2+1 字节 在最坏的情况下, 每个字符或许需要使用 2 个字节进行编码, 而且还需要终结 Null 字节 当 mysql_real_escape_string() 返回时, to 的内容是由 Null 终结的字符串 返回值是编码字符串的长度, 不包括终结用 Null 字符 如果需要更改连接的字符集, 应使用 mysql_set_character_set() 函数, 而不是执行 SET NAMES ( 或 SET CHARACTER SET) 语句 mysql_set_character_set() 的工作方式类似于 SET NAMES, 但它还能影响 mysql_real_escape_string() 所使用的字符集, 而 SET NAMES 则不能 示例 : char query[1000],*end; end = strmov(query,"insert INTO test_table values("); *end++ = '\''; end += mysql_real_escape_string(&mysql, end,"what's this",11); *end++ = '\''; *end++ = ','; *end++ = '\''; end += mysql_real_escape_string(&mysql, end,"binary data: \0\r\n",16); *end++ = '\''; *end++ = ')'; if (mysql_real_query(&mysql,query,(unsigned int) (end - query))) 第 42 页

47 成都天心悦高科技发展有限公司 fprintf(stderr, "Failed to insert row, Error: %s\n", mysql_error(&mysql)); 该示例中使用的 strmov() 函数包含在 mysqlclient 库中, 工作方式与 strcpy() 类似, 但会返回指向第 1 个参数终结用 Null 的指针 返回值置于 to 中的值的长度, 不包括终结用 Null 字符 错误无 mysql_real_query() int mysql_real_query(mysql *mysql, const char *query, unsigned long length) 描述执行由 query 指向的 SQL 查询, 它应是字符串长度字节 long 正常情况下, 字符串必须包含 1 条 SQL 语句, 而且不应为语句添加终结分号 ( ; ) 或 \g 如果允许多语句执行, 字符串可包含由分号隔开的多条语句 对于包含二进制数据的查询, 必须使用 mysql_real_query() 而不是 mysql_query(), 这是因为二进制数据可能会包含 \0 字符 此外,mysql_real_query() 比 mysql_query() 快, 这是因为它不会在查询字符串上调用 strlen() 如果希望知道查询是否应返回结果集, 可使 mysql_field_count() 进行检查 返回值如果查询成功, 返回 0 如果出现错误, 返回非 0 值 错误 CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_SERVER_LOST 在查询过程中, 与服务器的连接丢失 CR_UNKNOWN_ERROR 出现未知错误 mysql_refresh() 描述 int mysql_refresh(mysql *mysql, unsigned int options) 第 43 页

48 数字有机体工作库及大规模存储与管理系统开发手册 该函数用于刷新表或高速缓冲, 或复位复制服务器信息 连接的用户必须具有 RELOAD 权限 options 参量是一种位掩码, 由下述值的任意组合构成 能够以 Or ( 或 ) 方式将多个值组合在一起, 用一次调用执行多项操作 REFRESH_GRANT 刷新授权表, 与 FLUSH PRIVILEGES 类似 REFRESH_LOG 刷新日志, 与 FLUSH LOGS 类似 REFRESH_TABLES 刷新表高速缓冲, 与 FLUSH TABLES 类似 REFRESH_HOSTS 刷新主机高速缓冲, 与 FLUSH HOSTS 类似 REFRESH_STATUS 复位状态变量, 与 FLUSH STATUS 类似 REFRESH_THREADS 刷新线程高速缓冲 REFRESH_SLAVE 在从复制服务器上, 复位主服务器信息, 并重新启动从服务器, 与 RESET SLAVE 类似 REFRESH_MASTER 在主复制服务器上, 删除二进制日志索引中列出的二进制日志文件, 并截短索引文件, 与 RESET MASTER 类似 返回值 0 表示成功, 非 0 值表示出现错误 错误 CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_SERVER_LOST 在查询过程中, 与服务器的连接丢失 CR_UNKNOWN_ERROR 出现未知错误 mysql_reload() 描述 int mysql_reload(mysql *mysql) 第 44 页

49 成都天心悦高科技发展有限公司 请求 MySQL 服务器重新加载授权表 连接的用户必须具有 RELOAD 权限 该函数已过时 最好使用 mysql_query() 来发出 SQL FLUSH PRIVILEGES 语句 返回值 0 表示成功, 非 0 值表示出现错误 错误 CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_SERVER_LOST 在查询过程中, 与服务器的连接丢失 CR_UNKNOWN_ERROR 出现未知错误 mysql_rollback() my_bool mysql_rollback(mysql *mysql) 描述回滚当前事务 该函数的动作取决于 completion_type 系统变量的值 尤其是, 如果 completion_type 的值为 2, 终结事务后, 服务器将执行释放操作, 并关闭客户端连接 客户端程序应调用 mysql_close(), 从客户端一侧关闭连接 返回值如果成功, 返回 0, 如果出现错误, 返回非 0 值 错误无 mysql_row_seek() MYSQL_ROW_OFFSET mysql_row_seek(mysql_res *result, MYSQL_ROW_OFFSET offset) 描述将行光标置于查询结果集中的任意行 offset 值是行偏移量, 它应是从 mysql_row_tell() 或 mysql_row_seek() 返回的值 该值不是行编号, 如果你打算按编号查找结果集中的行, 请使用 mysql_data_seek() 该函数要求在结果集的结构中包含查询的全部结果, 因此 mysql_row_seek() 仅应与 mysql_store_result() 一起使用, 而不是与 mysql_use_result() 返回值 第 45 页

50 数字有机体工作库及大规模存储与管理系统开发手册 行光标的前一个值 该值可传递给对 mysql_row_seek() 的后续调用 错误无 mysql_row_tell() MYSQL_ROW_OFFSET mysql_row_tell(mysql_res *result) 描述对于上一个 mysql_fetch_row(), 返回行光标的当前位置 该值可用作 mysql_row_seek() 的参量 仅应在 mysql_store_result() 之后, 而不是 mysql_use_result() 之后使用 mysql_row_tell() 返回值行光标的当前偏移量 错误无 mysql_select_db() int mysql_select_db(mysql *mysql, const char *db) 描述使由 db 指定的数据库成为由 mysql 指定的连接上的默认数据库 ( 当前数据库 ) 在后续查询中, 该数据库将是未包含明确数据库区分符的表引用的默认数据库 除非已连接的用户具有使用数据库的权限, 否则 mysql_select_db() 将失败 返回值 0 表示成功, 非 0 值表示出现错误 错误 CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_SERVER_LOST 在查询过程中, 与服务器的连接丢失 CR_UNKNOWN_ERROR 出现未知错误 mysql_set_character_set() 描述 int mysql_set_character_set(mysql *mysql, char *csname) 第 46 页

51 成都天心悦高科技发展有限公司 该函数用于为当前连接设置默认的字符集 字符串 csname 指定了 1 个有效的字符集名称 连接校对成为字符集的默认校对 该函数的工作方式与 SET NAMES 语句类似, 但它还能设置 mysql->charset 的值, 从而影响了由 mysql_real_escape_string() 设置的字符集 返回值 0 表示成功, 非 0 值表示出现错误 示例 : MYSQL mysql; mysql_init(&mysql); if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,null,0)) fprintf(stderr, "Failed to connect to database: Error: %s\n", mysql_error(&mysql)); if (!mysql_set_charset_name(&mysql, "utf8")) printf("new client character set: %s\n", mysql_character_set_name(&mysql)); mysql_set_server_option() 描述 int mysql_set_server_option(mysql *mysql, enum enum_mysql_set_option option) 允许或禁止连接的选项 选项可以取下述值之一 : MYSQL_OPTION_MULTI_STATEMENTS_ON MYSQL_OPTION_MULTI_STATEMENTS_OFF 允许多语句支持 禁止多语句支持 返回值 0 表示成功, 非 0 值表示出现错误 错误 CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_SERVER_LOST 在查询过程中, 与服务器的连接丢失 ER_UNKNOWN_COM_ERROR 服务器不支持 mysql_set_server_option() 或服务器不支持试图设置的选项 第 47 页

52 数字有机体工作库及大规模存储与管理系统开发手册 mysql_shutdown() int mysql_shutdown(mysql *mysql, enum enum_shutdown_level shutdown_level) 描述请求数据库服务器关闭 已连接的用户必须具有 SHUTDOWN 权限 DosSQL 服务器仅支持 1 种关闭类型,shutdown_level 必须等效于 SHUTDOWN_DEFAULT 设计规划了额外的关闭级别, 以便能够选择所需的级别 对于用旧版本 libmysqlclient 头文件编译并调用 mysql_shutdown() 的动态链接可执行程序, 需要与旧版本的 libmysqlclient 动态库一起使用 返回值 0 表示成功, 非 0 值表示出现错误 错误 CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_SERVER_LOST 在查询过程中, 与服务器的连接丢失 CR_UNKNOWN_ERROR 出现未知错误 mysql_sqlstate() const char *mysql_sqlstate(mysql *mysql) 描述返回由 Null 终结的字符串, 该字符串包含关于上次错误的 SQLSTATE 错误代码 错误代码包含 5 个字符 '00000' 表示无错误 其值由 ANSI SQL 和 ODBC 指定 注意, 并非所有的 DosSQL 错误均会被映射到 SQLSTATE 错误代码 值 'HY000'( 一般错误 ) 用于未映射的错误 返回值包含 SQLSTATE 错误码的 由 Null 终结的字符串 mysql_ssl_set() int mysql_ssl_set(mysql *mysql, const char *key, const char *cert, const char *ca, const char *capath, const char *cipher) 描述使用 mysql_ssl_set(), 可采用 SSL 建立安全连接 必须在 mysql_real_connect() 之前调用它 第 48 页

53 成都天心悦高科技发展有限公司 除非在客户端库中允许了 OpenSSL 支持, 否则 mysql_ssl_set() 不作任何事 Mysql 是从 mysql_init() 返回的连接处理程序 其他参数的指定如下 : key 是 key 文件的路径名 cert 是证书文件的路径名 ca 是证书授权文件的路径名 capath 是指向目录的路径名, 该目录中包含以 pem 格式给出的受信任 SSL CA 证书 cipher 是允许密码的列表, 用于 SSL 加密 对于任何未使用的 SSL 参数, 可为其给定 NULL 返回值该函数总返回 0 如果 SSL 设置不正确, 当你尝试连接时,mysql_real_connect() 将返回错误 mysql_stat() char *mysql_stat(mysql *mysql) 描述返回包含特定信息的字符串, 该信息与 mysqladmin status 命令提供的信息类似 包括以秒为单位的正常运行时间, 以及运行线程的数目, 问题数, 再加载次数, 以及打开的表数目 返回值描述服务器状态的字符集 如果出现错误, 返回 NULL 错误 CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_SERVER_LOST 在查询过程中, 与服务器的连接丢失 CR_UNKNOWN_ERROR 出现未知错误 mysql_store_result() MYSQL_RES *mysql_store_result(mysql *mysql) 描述对于成功检索了数据的每个查询 (SELECT SHOW DESCRIBE EXPLAIN CHECK TABLE 等 ), 必须调用 mysql_store_result() 或 mysql_use_result() 第 49 页

54 数字有机体工作库及大规模存储与管理系统开发手册 对于其他查询, 不需要调用 mysql_store_result() 或 mysql_use_result(), 但是如果在任何情况下均调用了 mysql_store_result(), 它也不会导致任何伤害或性能降低 通过检查 mysql_store_result() 是否返回 0, 可检测查询是否没有结果集 ( 以后会更多 ) 如果希望了解查询是否应返回结果集, 可使 mysql_field_count() 进行检查 mysql_store_result() 将查询的全部结果读取到客户端, 分配 1 个 MYSQL_RES 结构, 并将结果置于该结构中 如果查询未返回结果集,mysql_store_result() 将返回 Null 指针 ( 例如, 如果查询是 INSERT 语句 ) 如果读取结果集失败,mysql_store_result() 还会返回 Null 指针 通过检查 mysql_error() 是否返回非空字符串,mysql_errno() 是否返回非 0 值, 或 mysql_field_count() 是否返回 0, 可以检查是否出现了错误 如果未返回行, 将返回空的结果集 ( 空结果集设置不同于作为返回值的空指针 ) 一旦调用了 mysql_store_result() 并获得了不是 Null 指针的结果, 可调用 mysql_num_rows() 来找出结果集中的行数 可以调用 mysql_fetch_row() 来获取结果集中的行, 或调用 mysql_row_seek() 和 mysql_row_tell() 来获取或设置结果集中的当前行位置 一旦完成了对结果集的操作, 必须调用 mysql_free_result() 返回值具有多个结果的 MYSQL_RES 结果集合 如果出现错误, 返回 NULL 错误如果成功,mysql_store_result() 将复位 mysql_error() 和 mysql_errno() CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令 CR_OUT_OF_MEMORY 内存溢出 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_SERVER_LOST 在查询过程中, 与服务器的连接丢失 CR_UNKNOWN_ERROR 出现未知错误 mysql_thread_id() 描述 unsigned long mysql_thread_id(mysql *mysql) 返回当前连接的线程 ID 该值可用作 mysql_kill() 的参量以杀死线程 第 50 页

55 成都天心悦高科技发展有限公司 如果连接丢失, 并使用 mysql_ping() 进行了再连接, 线程 ID 将改变 这意味着你不应获取线程 ID 并保存它供以后使用, 应在需要时获取它 返回值当前连接的线程 ID 错误无 mysql_use_result() MYSQL_RES *mysql_use_result(mysql *mysql) 描述对于成功检索数据的每个查询 (SELECT SHOW DESCRIBE EXPLAIN), 必须调用 mysql_store_result() 或 mysql_use_result() mysql_use_result() 将初始化结果集检索, 但并不像 mysql_store_result() 那样将结果集实际读取到客户端 它必须通过对 mysql_fetch_row() 的调用, 对每一行分别进行检索 这将直接从服务器读取结果, 而不会将其保存在临时表或本地缓冲区内, 与 mysql_store_result() 相比, 速度更快而且使用的内存也更少 客户端仅为当前行和通信缓冲区分配内存, 分配的内存可增加到 max_allowed_packet 字节 另一方面, 如果你正在客户端一侧为各行进行大量的处理操作, 或者将输出发送到了用户可能会键入 ^S ( 停止滚动 ) 的屏幕, 就不应使用 mysql_use_result() 这会绑定服务器, 并阻止其他线程更新任何表 ( 数据从这类表获得 ) 使用 mysql_use_result() 时, 必须执行 mysql_fetch_row(), 直至返回 NULL 值, 否则, 未获取的行将作为下一个检索的一部分返回 C API 给出命令不同步错误, 如果忘记了执行该操作, 将不能运行该命令 不应与从 mysql_use_result() 返回的结果一起使用 mysql_data_seek() mysql_row_seek() mysql_row_tell() mysql_num_rows() 或 mysql_affected_rows(), 也不应发出其他查询, 直至 mysql_use_result() 完成为止 ( 但是, 提取了所有行后,mysql_num_rows() 将准确返回提取的行数 ) 一旦完成了对结果集的操作, 必须调用 mysql_free_result() 使用 libmysqld 嵌入式服务器时, 由于在调用 mysql_free_result() 之前, 内存使用将随着每个检索的行增加, 内存效益将基本丧失 返回值 MYSQL_RES 结果结构 如果出现错误, 返回 NULL 错误如果成功,mysql_use_result() 将复位 mysql_error() 和 mysql_errno() CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令 CR_OUT_OF_MEMORY 第 51 页

56 数字有机体工作库及大规模存储与管理系统开发手册 内存溢出 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_SERVER_LOST 在查询过程中, 与服务器的连接丢失 CR_UNKNOWN_ERROR 出现未知错误 mysql_warning_count() unsigned int mysql_warning_count(mysql *mysql) 错误返回执行前一个 SQL 语句期间生成的告警数目 返回值告警计数 错误无 C API 预处理语句 DosSQL 客户端 / 服务器协议提供了预处理语句 该功能采用了由 mysql_stmt_init() 初始化函数返回的 MYSQL_STMT 语句处理程序数据结构 对于多次执行的语句, 预处理执行是一种有效的方式 首先对语句进行解析, 为执行作好准备 接下来, 在需要时使用初始化函数返回的语句句柄执行一次或多次 对于多次执行的语句, 预处理执行比直接执行快 主要原因在于, 仅对查询执行一次解析操作 在直接执行的情况下, 每次执行语句时, 均将进行查询 此外, 由于每次执行预处理语句时仅需发送参数的数据, 从而减少了网络通信量 预处理语句的另一个优点是, 它采用了二进制协议, 从而使得客户端和服务器之间的数据传输更有效率 下述语句可用作预处理语句 :CREATE TABLE DELETE DO INSERT REPLACE SELECT SET UPDATE 以及大多数 SHOW 语句 在 MySQL 5.1 中, 不支持其他语句 C API 预处理语句的数据类型 预处理语句主要使用 MYSQL_STMT 和 MYSQL_BIND 数据结构 第 3 种结构 MYSQL_TIME 用于传输暂时性数据 MYSQL_STMT 该结构表示预处理语句, 通过调用 mysql_stmt_init() 创建语句, 返回语句句柄, 即指向 MYSQL_STMT 的指针 该句柄用于所有后续的与语句有关的函数, 直至使用 mysql_stmt_close() 关闭了它为止 第 52 页

57 成都天心悦高科技发展有限公司 MYSQL_STMT 结构没有供应用程序使用的参数 此外, 不应尝试复制 MYSQL_STMT 结构, 不保证这类复制物会有用 多个语句句柄能够与单个连接关联起来 对句柄数目的限制取决于系统资源 MYSQL_BIND 该结构用于语句输入 ( 发送给服务器的数据值 ) 和输出 ( 从服务器返回的结果值 ) 对于输入, 它与 mysql_stmt_bind_param() 一起使用, 用于将参数数据值绑定到缓冲区上, 以供 mysql_stmt_execute() 使用 对于输出, 它与 mysql_stmt_bind_result() 一起使用, 用于绑定结果缓冲区, 以便用于 with mysql_stmt_fetch() 以获取行 MYSQL_BIND 结构包含下述供应用程序使用的成员 每个成员用于输入和输出, 但在某些时候, 也能用于不同的目的, 具体情况取决于数据传输的方向 enum enum_field_types buffer_type 缓冲的类型 在本节后面列出了允许的 buffer_type 值 对于输入,buffer_type 指明了与语句参数捆绑的值类型 对于输出, 它指明了你希望从结果缓冲区收到的值类型 void *buffer 对于输入, 这是指向存储语句参数数据值的缓冲的指针 对于输出, 它是指向返回结果集列值的缓冲的指针 对于数值列类型, 缓冲应指向恰当的 C 类型变量 ( 如果将该变量与具有 UNSIGNED 属性的列关联起来, 则为变量 unsigned C 类型 通过使用 is_unsigned 成员, 指明变量是 signed 或 unsigned 类型, 详情请参见本节后面的介绍 ) 对于日期和时间列类型, 缓冲应指向 MYSQL_TIME 结构 对于字符和二进制字符串列类型, 缓冲应指向字符缓冲区 unsigned long buffer_length *buffer 的实际大小, 单位为字节, 它指明了可保存在缓冲区内的最大数据 对于字符和二进制 C 数据,buffer_length 值指定了与 mysql_stmt_bind_param() 一起使用时的 *buffer 长度, 或与 mysql_stmt_bind_result() 一起使用时能够提取到缓冲区内的最大数据 unsigned long *length 指向 unsigned long 变量的指针, 该变量指明了存储在 *buffer 中数据的实际字节数 length 用于字符或二进制 C 数据 对于输入参数数据绑定, length 指向 unsigned long 变量, 该变量指明了存储在 *buffer 中参数值的长度, 供 mysql_stmt_execute() 使用 对于输出值绑定,mysql_stmt_fetch() 会将返回的列值保存到 length 指向的变量中 对于数值和临时数据类型, length 将被忽略, 原因在于该数据值的长度是由 buffer_type 值决定的 my_bool *is_null 该成员指向 my_bool 变量, 如果值为 NULL, 该变量为 真, 如果值为非 Null, 该变量为 假 对于输入, 将 *is_null 设置为 真, 指明以语句参数的形式传递 NULL 值 对于输出, 如果从语句返回的结果集列值为 NULL, 当获取了行后, 该值将被设为 真 is_null 是指向布尔类型的指针, 而不是布尔标量, 以便能以下述方式使用它 : 如果数据值总是 NULL, 使用 MYSQL_TYPE_NULL 绑定列 第 53 页

58 数字有机体工作库及大规模存储与管理系统开发手册 如果数据值总是 NOT NULL, 设置 is_null = (my_bool*) 0 在所有其他情况下, 应将 is_null 设置为 my_bool 变量的地址, 并在各次执行之间恰当地更改变量的值, 以指明数据值是 NULL 或 NOT NULL my_bool is_unsigned 该成员用于整数类型 ( 对应于 MYSQL_TYPE_TINY MYSQL_TYPE_SHORT MYSQL_TYPE_LONG 以及 MYSQL_TYPE_LONGLONG 类型的代码 ) 对于无符号类型, 应将 is_unsigned 设置为 真, 对于带符号类型, 应将其设置为 假 my_bool error 对于输出, 该成员用于通报数据截短错误 必须通过调用带有 MYSQL_REPORT_DATA_TRUNCATION 选项的 mysql_options(), 启用截短通报功能 允许该功能后,mysql_stmt_fetch() 返回 MYSQL_DATA_TRUNCATED, 而且对于出现截短情况的参数, 在 MYSQL_BIND 结构中, 错误标志为 真 截短指明丢失了符号或有效位数, 或字符串过长以至于无法容纳在 1 列中 要想使用 MYSQL_BIND 结构, 应将其内容置为 0 以便初始化它, 然后对其进行设置, 恰当地描述它 例如, 要想声明并初始化三个 MYSQL_BIND 结构的数组, 可使用下述代码 : MYSQL_BIND bind[3];.0 memset(bind, 0, sizeof(bind)); MYSQL_TIME 该结构用于将 DATE TIME DATETIME 和 TIMESTAMP 数据直接发送到服务器, 或从服务器直接接收这类数据 将 MYSQL_BIND 结构的 buffer_type 成员设置为临时值之一, 并将 buffer 成员设置为指向 MYSQL_TIME 结构, 即可实现该点 MYSQL_TIME 结构包含下述成员 : unsigned int year 年份 unsigned int month 月份 unsigned int day 天 unsigned int hour 小时 unsigned int minute 分钟 unsigned int second 秒 my_bool neg 布尔标志, 用于指明时间是否为负数 unsigned long second_part 第 54 页

59 成都天心悦高科技发展有限公司 秒的分数部分, 该成员目前不使用 仅使用施加在给定临时类型值上的 MYSQL_TIME 结构的部分 : 用于 DATE DATETIME 和 TIMESTAMP 的年 月 日部分 用于 TIME DATETIME 和 TIMESTAMP 值的小时 分钟 秒部分 在下面的表格中, 给出了可在 MYSQL_BIND 结构的 buffer_type 成员中指定的允许值 在该表中, 还给出了与每个 buffer_type 值最接近的对应 SQL 类型, 对于数值和临时类型, 给出了对应的 C 类型 buffer_type 值 SQL 类型 C 类型 MYSQL_TYPE_TINY TINYINT char MYSQL_TYPE_SHORT SMALLINT short int MYSQL_TYPE_LONG INT int MYSQL_TYPE_LONGLONG BIGINT long long int MYSQL_TYPE_FLOAT FLOAT float MYSQL_TYPE_DOUBLE DOUBLE double MYSQL_TYPE_TIME TIME MYSQL_TIME MYSQL_TYPE_DATE DATE MYSQL_TIME MYSQL_TYPE_DATETIME DATETIME MYSQL_TIME MYSQL_TYPE_TIMESTAMP TIMESTAMP MYSQL_TIME MYSQL_TYPE_STRING MYSQL_TYPE_VAR_STRING MYSQL_TYPE_TINY_BLOB MYSQL_TYPE_BLOB MYSQL_TYPE_MEDIUM_BLOB MYSQL_TYPE_LONG_BLOB 隐式类型转换可沿两个方向执行 C API 预处理语句函数概述 CHAR VARCHAR TINYBLOB/TINYTEXT BLOB/TEXT MEDIUMBLOB/MEDIUMTEXT LONGBLOB/LONGTEXT 函数列表 在此归纳了预处理语句处理功能可使用的函数, 并在后面的章节中作了详细的介绍 函数 描述 mysql_stmt_affected_rows() 返回由预处理语句 UPDATE DELETE 或 INSERT 变更 删除或插入的行数目 mysql_stmt_attr_get() 获取预处理语句属性的值 mysql_stmt_attr_set() 设置预处理语句的属性 mysql_stmt_bind_param() 将应用程序数据缓冲并与预处理 SQL 语句中的参数标记符关联起来 mysql_stmt_bind_result() 将应用程序数据缓冲并与结果集中的列关联起来 第 55 页

60 数字有机体工作库及大规模存储与管理系统开发手册 mysql_stmt_close() 释放预处理语句使用的内存 mysql_stmt_data_seek() 寻找语句结果集中的任意行编号 mysql_stmt_errno() 返回上次语句执行的错误编号 mysql_stmt_error() 返回上次语句执行的错误消息 mysql_stmt_execute() 执行预处理语句 mysql_stmt_fetch() 从结果集获取数据的下一行, 并返回所有绑定列的数据 mysql_stmt_fetch_column() 获取结果集当前行中某列的数据 mysql_stmt_field_count() 对于最近的语句, 返回结果行的数目 mysql_stmt_free_result() 释放分配给语句句柄的资源 mysql_stmt_init() 为 MYSQL_STMT 结构分配内存并初始化它 mysql_stmt_insert_id() 对于预处理语句的 AUTO_INCREMENT 列, 返回生成的 ID mysql_stmt_num_rows() 从语句缓冲结果集返回总行数 mysql_stmt_param_count() 返回预处理 SQL 语句中的参数数目 mysql_stmt_param_metadata() 返回结果集的参数元数据 mysql_stmt_prepare() 为执行操作准备 SQL 字符串 mysql_stmt_reset() 复位服务器中的语句缓冲区 mysql_stmt_result_metadata() 以结果集形式返回预处理语句元数据 mysql_stmt_row_seek() 使用从 mysql_stmt_row_tell() 返回的值, 查找语句结果集中的行偏移 mysql_stmt_row_tell() 返回语句行光标位置 mysql_stmt_send_long_data() 将程序块中的长数据发送到服务器 mysql_stmt_sqlstate() 返回关于上次语句执行的 SQLSTATE 错误代码 mysql_stmt_store_result() 将完整的结果集检索到客户端 调用 mysql_stmt_init() 以创建语句句柄, 然后调用 mysql_stmt_prepare 准备语句, 调用 mysql_stmt_bind_param() 提供参数数据, 并调用 mysql_stmt_execute() 执行语句 通过更改 mysql_stmt_bind_param() 提供的相应缓冲区中的参数值, 可重复执行 mysql_stmt_execute() 如果语句是 SELECT 或任何其他能生成结果集的语句,mysql_stmt_prepare() 也会通过 mysql_stmt_result_metadata() 以 MYSQL_RES 结果集的形式返回结果集元数据信息 你可以使用 mysql_stmt_bind_result() 提供结果缓冲, 以便 mysql_stmt_fetch() 能自动将 数据返回给这些缓冲 这是一种按行获取方式 此外, 你也能使用 mysql_stmt_send_long_data() 将程序块中的文本或二进制数据发送到 服务器 完成语句执行后, 必须使用 mysql_stmt_close() 关闭语句句柄, 以便与之相关的所有资 源均能被释放 如果通过调用 mysql_stmt_result_metadata() 获得了 SELECT 语句的结果集元数据, 也 应使用 mysql_free_result() 释放元数据 第 56 页

61 成都天心悦高科技发展有限公司 执行步骤 要想准备和执行语句, 应用程序必须采取下述步骤 : 1. 用 msyql_stmt_init() 创建预处理语句句柄 要想在服务器上准备预处理语句, 可调用 mysql_stmt_prepare(), 并为其传递包含 SQL 语句的字符串 2. 如果语句生成了结果集, 调用 mysql_stmt_result_metadata() 以获得结果集元数据 与包含查询返回列的结果集不同, 该元数据本身也采用了结果集的形式 元数据结果集指明了结果中包含多少列, 并包含每一列的信息 3. 使用 mysql_stmt_bind_param() 设置任何参数的值 必须设置所有参数, 否则语句执行将返回错误, 或生成无法预料的结果 4. 调用 mysql_stmt_execute() 执行语句 5. 如果语句生成了结果集, 捆绑数据缓冲, 通过调用 mysql_stmt_bind_result(), 检索行值 6. 通过重复调用 mysql_stmt_fetch(), 按行将数据提取到缓冲区, 直至未发现更多行为止 7. 通过更改参数值并再次执行语句, 重复步骤 3 到步骤 6 调用 mysql_stmt_prepare() 时,MySQL 客户端 / 服务器协议将执行下述操作 : 服务器解析语句, 并通过赋值语句 ID 将 OK 状态发回客户端 此外, 如果它是面向结果集的语句, 还将发送总的参数数目, 列计数和元数据 在此调用过程中, 服务器将检查语句的所有语法和语义 客户端采用该语句 ID 用于进一步操作, 以便服务器能从其语句池中识别语句 调用 mysql_stmt_execute() 时,MySQL 客户端 / 服务器协议将执行下述操作 : 客户端使用语句句柄, 并将参数数据发送到服务器 服务器使用由客户端提供的 ID 来识别语句, 用新提供的数据替换参数标记符, 并执行语句 如果语句生成了结果集, 服务器将数据发回客户端 否则, 服务器将会发送 OK 状态, 以及总的变更 删除和插入行数 调用 mysql_stmt_fetch() 时,MySQL 客户端 / 服务器协议将执行下述操作 : 客户端按行从信息包读取数据, 并通过执行必要的转换操作将其放入应用程序数据缓冲中 如果应用程序的缓冲类型与服务器返回的字段类型相同, 转换十分简明 如果出现了错误, 可分别使用 mysql_stmt_errno() mysql_stmt_error() 和 mysql_stmt_sqlstate() 获取语句错误代码 错误消息和 SQLSTATE 值 预处理语句日志功能 对于与 mysql_stmt_prepare() 和 mysql_stmt_execute() C API 函数一起执行的预处理语句, 服务器会将 准备 和 执行 行写入一般查询日志, 以便你能了解语句是在何时准备和执行的 假定按下述方式准备和执行了语句 : 1. 调用 mysql_stmt_prepare() 以准备语句字符串 "SELECT?" 2. 调用 mysql_stmt_bind_param() 将值 3 绑定到预处理语句中的参数 第 57 页

62 数字有机体工作库及大规模存储与管理系统开发手册 3. 调用 mysql_stmt_execute(), 执行预处理语句 上述调用的结果是, 服务器将下述行写入一般查询日志 : Prepare [1] SELECT? Execute [1] SELECT 3 日志中的每个 准备 和 执行 行均具有 [n] 语句 ID 标识, 这样你就能跟踪已记录的预处理语句 n 是正整数 对于客户端, 如果同时有多个活动的预处理语句,n 可能会大于 1 替换了? 参数的数据值后, 每个 执行 行将显示一条预处理语句 C API 预处理语句函数描述 为了准备和执行查询, 请使用下述部分详细介绍的函数 注意, 与 MYSQL_STMT 结构一起使用的所有函数均以前缀 mysql_stmt_ 开始 要想创建 MYSQL_STMT 句柄, 请使用 mysql_stmt_init() 函数 mysql_stmt_affected_rows() my_ulonglong mysql_stmt_affected_rows(mysql_stmt *stmt) 描述返回上次执行语句更改 删除或插入的总行数 对于 UPDATE DELETE 或 INSERT 语句, 可在 mysql_stmt_execute() 之后立刻调用它们 对于 SELECT 语句, mysql_stmt_affected_rows() 的工作方式类似于 mysql_num_rows() 返回值大于 0 的整数指明了受影响或检索的行数 对于 UPDATE 语句, 0 表明未更新任何记录, 在查询中没有与 WHERE 子句匹配的行, 或尚未执行任何查询 -1 表明返回了错误, 或对 SELECT 查询, 在调用 mysql_stmt_store_result() 之前调用了 mysql_stmt_affected_rows() 由于 mysql_stmt_affected_rows() 返回无符号值, 可通过比较返回值和 (my_ulonglong)-1 ( 或等效的 (my_ulonglong)~0 ), 检查 -1 错误无 mysql_stmt_attr_get() int mysql_stmt_attr_get(mysql_stmt *stmt, enum enum_stmt_attr_type option, void *arg) 描述可用于获得语句属性的当前值 option 参量是希望获取的选项, arg 应指向包含选项值的变量 如果 option 是整数, 那么 arg 应指向整数的值 返回值如果是 OK, 返回 0 如果选项未知, 返回非 0 值 第 58 页

63 成都天心悦高科技发展有限公司 错误 无 mysql_stmt_attr_set() int mysql_stmt_attr_set(mysql_stmt *stmt, enum enum_stmt_attr_type option, const void *arg) 描述可用于影响预处理语句的行为 可多次调用该函数来设置多个选项 option 参量是希望设置的选项, arg 参量是选项的值 如果 option 是整数, 那么 arg 应指向整数的值 可能的选项值 : 选项 STMT_ATTR_UPDATE_MAX_LENGTH STMT_ATTR_CURSOR_TYPE STMT_ATTR_PREFETCH_ROWS 参量类型 my_bool * unsigned long * unsigned long * 功能如果设为 1: 更新 mysql_stmt_store_result() 中的元数据 MYSQL_FIELD->max_length 调用 mysql_stmt_execute() 时, 语句将打开的光标类型 *arg 可以是 CURSOR_TYPE_NO_CURSOR( 默认值 ) 或 CURSOR_TYPE_READ_ONLY 使用光标时, 一次从服务器获取的行数 *arg 的范围从 1 到 unsigned long 的最大值, 默认值为 1 如果与 CURSOR_TYPE_READ_ONLY 一起使用了 STMT_ATTR_CURSOR_TYPE 选项, 当调用了 mysql_stmt_execute() 时, 将为语句打开光标 如果存在由前一个 mysql_stmt_execute() 调用打开的光标, 在打开新的光标前, 将关闭该光标 此外, 为再执行而准备语句之前,mysql_stmt_reset() 还将关闭任何打开的光标 mysql_stmt_free_result() 将关闭任何打开的光标 如果为预处理语句打开了光标, 没必要调用 mysql_stmt_store_result(), 这是因为, 该函数会导致在客户端一侧对结果集进行缓冲处理 在 MySQL 中增加了 STMT_ATTR_CURSOR_TYPE 选项 在 MySQL 中, 增加了 STMT_ATTR_PREFETCH_ROWS 选项 返回值如果是 OK, 返回 0 如果选项未知, 返回非 0 值 错误无 示例 : 第 59 页

64 数字有机体工作库及大规模存储与管理系统开发手册 在下述示例中, 为预处理语句打开了 1 个光标, 并将每次获取的行数设为 5: MYSQL_STMT *stmt; int rc; unsigned long type; unsigned long prefetch_rows = 5; stmt = mysql_stmt_init(mysql); type = (unsigned long) CURSOR_TYPE_READ_ONLY; rc = mysql_stmt_attr_set(stmt, STMT_ATTR_CURSOR_TYPE, (void*) &type); /*... check return value... */ rc = mysql_stmt_attr_set(stmt, STMT_ATTR_PREFETCH_ROWS, (void*) &prefetch_rows); /*... check return value... */ mysql_stmt_bind_param() my_bool mysql_stmt_bind_param(mysql_stmt *stmt, MYSQL_BIND *bind) 描述 mysql_stmt_bind_param() 用于为 SQL 语句中的参数标记符绑定数据, 以传递给 mysql_stmt_prepare() 它使用 MYSQL_BIND 结构来提供数据 bind 是 MYSQL_BIND 结构的某一数组的地址 按照客户端库的预期, 对于查询中出现的每个? 参数标记符, 数组中均包含 1 个元素 假定你准备了下述语句 : INSERT INTO mytbl VALUES(?,?,?) 绑定参数时,MYSQL_BIND 结构的数组包含 3 个元素, 并能声明如下 : MYSQL_BIND bind[3]; 在 C API 预处理语句的数据类型 中, 介绍了应设置的每个 MYSQL_BIND 元素的成员 返回值如果绑定成功, 返回 0 如果出现错误, 返回非 0 值 错误 CR_INVALID_BUFFER_USE 指明 bind ( 绑定 ) 是否将提供程序块中的长数据, 以及缓冲类型是否为非字符串或二进制类型 CR_UNSUPPORTED_PARAM_TYPE 不支持该转换 或许 buffer_type 值是非法的, 或不是所支持的类型之一 CR_OUT_OF_MEMORY 内存溢出 CR_UNKNOWN_ERROR 出现未知错误 第 60 页

65 成都天心悦高科技发展有限公司 示例 : 关于 mysql_stmt_bind_param() 的用法, 请参见 mysql_stmt_execute() 给出的示例 mysql_stmt_bind_result() my_bool mysql_stmt_bind_result(mysql_stmt *stmt, MYSQL_BIND *bind) 描述 mysql_stmt_bind_result() 用于将结果集中的列与数据缓冲和长度缓冲关联 ( 绑定 ) 起来 当调用 mysql_stmt_fetch() 以获取数据时,MySQL 客户端 / 服务器协议会将绑定列的数据置于指定的缓冲区内 调用 mysql_stmt_fetch() 之前, 必须将所有列绑定到缓冲 bind 是 MYSQL_BIND 结构某一数组的地址 按照客户端库的预期, 对于结果集中的每一列, 数组应包含相应的元素 如果未将列绑定到 MYSQL_BIND 结构,mysql_stmt_fetch() 将简单地忽略数据获取操作 缓冲区应足够大, 足以容纳数据值, 这是因为协议不返回成块的数据值 可以在任何时候绑定或再绑定列, 即使已部分检索了结果集后也同样 新的绑定将在下一次调用 mysql_stmt_fetch() 时起作用 假定某一应用程序绑定了结果集中的列, 并调用了 mysql_stmt_fetch() 客户端/ 服务器协议将返回绑定缓冲区中的数据 接下来, 假定应用程序将多个列绑定到不同的缓冲, 该协议不会将数据置于新绑定的缓冲区, 直至下次调用 mysql_stmt_fetch() 为止 要想绑定列, 应用程序将调用 mysql_stmt_bind_result(), 并传递类型 地址 以及长度缓冲的地址 在 C API 预处理语句的数据类型 中, 介绍了应设置的各 MYSQL_BIND 元素的成员 返回值如果绑定成功, 返回 0 如果出现错误, 返回非 0 值 错误 CR_UNSUPPORTED_PARAM_TYPE 不支持该转换 或许 buffer_type 值是非法的, 或不是所支持的类型之一 CR_OUT_OF_MEMORY 内存溢出 CR_UNKNOWN_ERROR 出现未知错误 示例 : 关于 mysql_stmt_bind_result() 的用法, 请见 mysql_stmt_fetch() 中给出的示例 mysql_stmt_close() my_bool mysql_stmt_close(mysql_stmt *) 描述关闭预处理语句 此外,mysql_stmt_close() 还会取消由 stmt 指向的语句句柄分配 第 61 页

66 数字有机体工作库及大规模存储与管理系统开发手册 如果当前语句已挂起或未读取结果, 该函数将取消它们, 以便能执行下一个查询, 返回值如果成功释放了语句, 返回 0 如果出现错误, 返回非 0 值 错误 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_UNKNOWN_ERROR 出现未知错误 示例 : 关于 mysql_stmt_close() 的用法, 请见 mysql_stmt_execute() 中给出的示例 mysql_stmt_data_seek() void mysql_stmt_data_seek(mysql_stmt *stmt, my_ulonglong offset) 描述查找语句结果集中的任意行 偏移量为行编号, 应位于从 0 到 mysql_stmt_num_rows(s tmt)-1 的范围内 该函数要求语句结果集结构包含上次执行查询的全部结果, 这样,mysql_stmt_data_se ek() 就能与 mysql_stmt_store_result() 一起使用 返回值无 错误无 mysql_stmt_errno() unsigned int mysql_stmt_errno(mysql_stmt *stmt) 描述对于由 stmt 指定的语句,mysql_stmt_errno() 将返回最近调用的语句 API 函数的错误代码, 该函数或成功或失败 0 返回值表示未出现错误 在 MySQL errmsg.h 头文件中列出了客户端错误消息编号 在 mysqld_error.h 中, 列出了服务器错误消息 返回值错误代码值 如果未出现错误, 返回 0 错误无 mysql_stmt_error() const char *mysql_stmt_error(mysql_stmt *stmt) 第 62 页

67 成都天心悦高科技发展有限公司 描述对于由 stmt 指定的语句,mysql_stmt_error() 返回由 Null 终结的字符串, 该字符串包含最近调用的语句 API 函数的错误消息, 该函数或成功或失败 如果未出现错误, 返回空字符串 ("") 这意味着下述两个测试是等效的: if (mysql_stmt_errno(stmt)) // an error occurred if (mysql_stmt_error(stmt)[0]) // an error occurred 通过重新编译 MySQL 客户端库, 可更改客户端错误消息的语言 目前, 能够选择数种语言之一显示错误消息 返回值描述了错误的字符串 如果未出现错误, 返回空字符串 错误无 mysql_stmt_execute() int mysql_stmt_execute(mysql_stmt *stmt) 描述 mysql_stmt_execute() 执行与语句句柄相关的预处理查询 在该调用期间, 将当前绑定的参数标记符的值发送到服务器, 服务器用新提供的数据替换标记符 如果语句是 UPDATE DELETE 或 INSERT, 通过调用 mysql_stmt_affected_rows(), 可发现更改 删除或插入的总行数 如果这是诸如 SELECT 等能生成结果集的语句, 调用任何其他能导致查询处理的函数之前, 必须调用 mysql_stmt_fetch() 来获取数据 对于生成结果集的语句, 执行语句之前, 可通过调用 mysql_stmt_attr_set(), 请求 mysql_stmt_execute() 为语句打开光标 如果多次执行某一语句, 在打开新的光标前, mysql_stmt_execute() 将关闭任何已打开的光标 返回值如果执行成功, 返回 0 如果出现错误, 返回非 0 值 错误 CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令 CR_OUT_OF_MEMORY 第 63 页

68 数字有机体工作库及大规模存储与管理系统开发手册 内存溢出 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_SERVER_LOST 在查询过程中, 与服务器的连接丢失 CR_UNKNOWN_ERROR 出现未知错误 示例 : 在下面的示例中, 介绍了使用 mysql_stmt_init() mysql_stmt_prepare() mysql_stmt_param_count() mysql_stmt_bind_param() mysql_stmt_execute() 以及 mysql_stmt_affected_rows() 创建和填充表的方法 假定 mysql 变量具有有效的连接句柄 #define STRING_SIZE 50 #define DROP_SAMPLE_TABLE "DROP TABLE IF EXISTS test_table" #define CREATE_SAMPLE_TABLE "CREATE TABLE test_table(col1 INT,\ col2 VARCHAR(40),\ col3 SMALLINT,\ col4 TIMESTAMP)" #define INSERT_SAMPLE "INSERT INTO test_table(col1,col2,col3) VALUES(?,?,?)" MYSQL_STMT *stmt; MYSQL_BIND bind[3]; my_ulonglong affected_rows; int param_count; short small_data; int int_data; char str_data[string_size]; unsigned long str_length; my_bool is_null; if (mysql_query(mysql, DROP_SAMPLE_TABLE)) fprintf(stderr, " DROP TABLE failed\n"); fprintf(stderr, " %s\n", mysql_error(mysql)); exit(0); if (mysql_query(mysql, CREATE_SAMPLE_TABLE)) fprintf(stderr, " CREATE TABLE failed\n"); fprintf(stderr, " %s\n", mysql_error(mysql)); exit(0); 第 64 页

69 成都天心悦高科技发展有限公司 /* Prepare an INSERT query with 3 parameters */ /* (the TIMESTAMP column is not named; the server */ /* sets it to the current date and time) */ stmt = mysql_stmt_init(mysql); if (!stmt) fprintf(stderr, " mysql_stmt_init(), out of memory\n"); exit(0); if (mysql_stmt_prepare(stmt, INSERT_SAMPLE, strlen(insert_sample))) fprintf(stderr, " mysql_stmt_prepare(), INSERT failed\n"); fprintf(stderr, " %s\n", mysql_stmt_error(stmt)); exit(0); fprintf(stdout, " prepare, INSERT successful\n"); /* Get the parameter count from the statement */ param_count= mysql_stmt_param_count(stmt); fprintf(stdout, " total parameters in INSERT: %d\n", param_count); if (param_count!= 3) /* validate parameter count */ fprintf(stderr, " invalid parameter count returned by MySQL\n"); exit(0); /* Bind the data for all 3 parameters */ memset(bind, 0, sizeof(bind)); /* INTEGER PARAM */ /* This is a number type, so there is no need to specify buffer_length */ bind[0].buffer_type= MYSQL_TYPE_LONG; bind[0].buffer= (char *)&int_data; bind[0].is_null= 0; bind[0].length= 0; /* STRING PARAM */ bind[1].buffer_type= MYSQL_TYPE_STRING; bind[1].buffer= (char *)str_data; bind[1].buffer_length= STRING_SIZE; 第 65 页

70 数字有机体工作库及大规模存储与管理系统开发手册 bind[1].is_null= 0; bind[1].length= &str_length; /* SMALLINT PARAM */ bind[2].buffer_type= MYSQL_TYPE_SHORT; bind[2].buffer= (char *)&small_data; bind[2].is_null= &is_null; bind[2].length= 0; /* Bind the buffers */ if (mysql_stmt_bind_param(stmt, bind)) fprintf(stderr, " mysql_stmt_bind_param() failed\n"); fprintf(stderr, " %s\n", mysql_stmt_error(stmt)); exit(0); /* Specify the data values for the first row */ int_data= 10; /* integer */ strncpy(str_data, "MySQL", STRING_SIZE); /* string */ str_length= strlen(str_data); /* INSERT SMALLINT data as NULL */ is_null= 1; /* Execute the INSERT statement - 1*/ if (mysql_stmt_execute(stmt)) fprintf(stderr, " mysql_stmt_execute(), 1 failed\n"); fprintf(stderr, " %s\n", mysql_stmt_error(stmt)); exit(0); /* Get the total number of affected rows */ affected_rows= mysql_stmt_affected_rows(stmt); fprintf(stdout, " total affected rows(insert 1): %lu\n", (unsigned long) affected_rows); if (affected_rows!= 1) /* validate affected rows */ fprintf(stderr, " invalid affected rows by MySQL\n"); exit(0); 第 66 页

71 成都天心悦高科技发展有限公司 /* Specify data values for second row, then re-execute the statement */ int_data= 1000; strncpy(str_data, "The most popular Open Source database", STRING_SIZE); str_length= strlen(str_data); small_data= 1000; /* smallint */ is_null= 0; /* reset */ /* Execute the INSERT statement - 2*/ if (mysql_stmt_execute(stmt)) fprintf(stderr, " mysql_stmt_execute, 2 failed\n"); fprintf(stderr, " %s\n", mysql_stmt_error(stmt)); exit(0); /* Get the total rows affected */ affected_rows= mysql_stmt_affected_rows(stmt); fprintf(stdout, " total affected rows(insert 2): %lu\n", (unsigned long) affected_rows); if (affected_rows!= 1) /* validate affected rows */ fprintf(stderr, " invalid affected rows by MySQL\n"); exit(0); /* Close the statement */ if (mysql_stmt_close(stmt)) fprintf(stderr, " failed while closing the statement\n"); fprintf(stderr, " %s\n", mysql_stmt_error(stmt)); exit(0); mysql_stmt_fetch() int mysql_stmt_fetch(mysql_stmt *stmt) 描述 mysql_stmt_fetch() 返回结果集中的下一行 仅能当结果集存在时调用它, 也就是说, 调用了能创建结果集的 mysql_stmt_execute() 之后, 或当 mysql_stmt_execute() 对整个结果集即行缓冲处理后调用了 mysql_stmt_store_result() 第 67 页

72 数字有机体工作库及大规模存储与管理系统开发手册 使用 mysql_stmt_bind_result() 绑定的缓冲,mysql_stmt_fetch() 返回行数据 对于当前列集合中的所有列, 它将返回缓冲内的数据, 并将长度返回到长度指针 调用 mysql_stmt_fetch() 之前, 应用程序必须绑定所有列 如果获取的数据值是 NULL 值, 对应 MYSQL_BIND 结构的 *is_null 值将包含 TRUE (1) 否则, 将根据应用程序指定的缓冲类型, 在 *buffer 和 *length 内返回数据及其长度 每个数值类型和临时类型都有固定的长度, 请参见下面的表格 字符串类型的长度取决于由 data_length 指明的实际数据值的长度 类型长度 MYSQL_TYPE_TINY 1 MYSQL_TYPE_SHORT 2 MYSQL_TYPE_LONG 4 MYSQL_TYPE_LONGLONG 8 MYSQL_TYPE_FLOAT 4 MYSQL_TYPE_DOUBLE 8 MYSQL_TYPE_TIME sizeof(mysql_time) MYSQL_TYPE_DATE sizeof(mysql_time) MYSQL_TYPE_DATETIME sizeof(mysql_time) MYSQL_TYPE_STRING data length MYSQL_TYPE_BLOB data_length 返回值返回值描述 0 成功, 数据被提取到应用程序数据缓冲区 出现错误 通过调用 mysql_stmt_errno() 和 1 mysql_stmt_error(), 可获取错误代码和错误消息 MYSQL_NO_DATA 不存在行 / 数据 MYSQL_DATA_TRUNCATED 出现数据截短 不返回 MYSQL_DATA_TRUNCATED, 除非用 mysql_options() 启用了截短通报功能 返回该值时, 为了确定截短的参数是哪个, 可检查 MYSQL_BIND 参数结构的错误成员 错误 CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令 CR_OUT_OF_MEMORY 内存溢出 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_SERVER_LOST 在查询过程中, 与服务器的连接丢失 第 68 页

73 成都天心悦高科技发展有限公司 CR_UNKNOWN_ERROR 出现未知错误 CR_UNSUPPORTED_PARAM_TYPE 缓冲类型为 MYSQL_TYPE_DATE MYSQL_TYPE_TIME MYSQL_TYPE_DATETIME 或 MYSQL_TYPE_TIMESTAMP, 但数据类型不是 DATE TIME DATETIME 或 TIMESTAMP 从 mysql_stmt_bind_result() 返回所有其他不支持的转换错误 示例 : 在下面的示例中, 介绍了使用 mysql_stmt_result_metadata() mysql_stmt_bind_result() 和 mysql_stmt_fetch() 从表中获取数据的方法 假定 mysql 变量具有有效的连接句柄 #define STRING_SIZE 50 #define SELECT_SAMPLE "SELECT col1, col2, col3, col4 FROM test_table" MYSQL_STMT *stmt; MYSQL_BIND bind[4]; MYSQL_RES *prepare_meta_result; MYSQL_TIME ts; unsigned long length[4]; int param_count, column_count, row_count; short small_data; int int_data; char str_data[string_size]; my_bool is_null[4]; /* Prepare a SELECT query to fetch data from test_table */ stmt = mysql_stmt_init(mysql); if (!stmt) fprintf(stderr, " mysql_stmt_init(), out of memory\n"); exit(0); if (mysql_stmt_prepare(stmt, SELECT_SAMPLE, strlen(select_sample))) fprintf(stderr, " mysql_stmt_prepare(), SELECT failed\n"); fprintf(stderr, " %s\n", mysql_stmt_error(stmt)); exit(0); fprintf(stdout, " prepare, SELECT successful\n"); /* Get the parameter count from the statement */ param_count= mysql_stmt_param_count(stmt); fprintf(stdout, " total parameters in SELECT: %d\n", param_count); 第 69 页

74 数字有机体工作库及大规模存储与管理系统开发手册 if (param_count!= 0) /* validate parameter count */ fprintf(stderr, " invalid parameter count returned by MySQL\n"); exit(0); /* Fetch result set meta information */ prepare_meta_result = mysql_stmt_result_metadata(stmt); if (!prepare_meta_result) fprintf(stderr, " mysql_stmt_result_metadata(), returned no meta information\n"); fprintf(stderr, " %s\n", mysql_stmt_error(stmt)); exit(0); /* Get total columns in the query */ column_count= mysql_num_fields(prepare_meta_result); fprintf(stdout, " total columns in SELECT statement: %d\n", column_count); if (column_count!= 4) /* validate column count */ fprintf(stderr, " invalid column count returned by MySQL\n"); exit(0); /* Execute the SELECT query */ if (mysql_stmt_execute(stmt)) fprintf(stderr, " mysql_stmt_execute(), failed\n"); fprintf(stderr, " %s\n", mysql_stmt_error(stmt)); exit(0); /* Bind the result buffers for all 4 columns before fetching them */ memset(bind, 0, sizeof(bind)); /* INTEGER COLUMN */ bind[0].buffer_type= MYSQL_TYPE_LONG; bind[0].buffer= (char *)&int_data; bind[0].is_null= &is_null[0]; bind[0].length= &length[0]; /* STRING COLUMN */ 第 70 页

75 成都天心悦高科技发展有限公司 bind[1].buffer_type= MYSQL_TYPE_STRING; bind[1].buffer= (char *)str_data; bind[1].buffer_length= STRING_SIZE; bind[1].is_null= &is_null[1]; bind[1].length= &length[1]; /* SMALLINT COLUMN */ bind[2].buffer_type= MYSQL_TYPE_SHORT; bind[2].buffer= (char *)&small_data; bind[2].is_null= &is_null[2]; bind[2].length= &length[2]; /* TIMESTAMP COLUMN */ bind[3].buffer_type= MYSQL_TYPE_TIMESTAMP; bind[3].buffer= (char *)&ts; bind[3].is_null= &is_null[3]; bind[3].length= &length[3]; /* Bind the result buffers */ if (mysql_stmt_bind_result(stmt, bind)) fprintf(stderr, " mysql_stmt_bind_result() failed\n"); fprintf(stderr, " %s\n", mysql_stmt_error(stmt)); exit(0); /* Now buffer all results to client */ if (mysql_stmt_store_result(stmt)) fprintf(stderr, " mysql_stmt_store_result() failed\n"); fprintf(stderr, " %s\n", mysql_stmt_error(stmt)); exit(0); /* Fetch all rows */ row_count= 0; fprintf(stdout, "Fetching results...\n"); while (!mysql_stmt_fetch(stmt)) row_count++; fprintf(stdout, " row %d\n", row_count); /* column 1 */ fprintf(stdout, " column1 (integer): "); 第 71 页

76 数字有机体工作库及大规模存储与管理系统开发手册 if (is_null[0]) fprintf(stdout, " NULL\n"); else fprintf(stdout, " %d(%ld)\n", int_data, length[0]); /* column 2 */ fprintf(stdout, " column2 (string) : "); if (is_null[1]) fprintf(stdout, " NULL\n"); else fprintf(stdout, " %s(%ld)\n", str_data, length[1]); /* column 3 */ fprintf(stdout, " column3 (smallint) : "); if (is_null[2]) fprintf(stdout, " NULL\n"); else fprintf(stdout, " %d(%ld)\n", small_data, length[2]); /* column 4 */ fprintf(stdout, " column4 (timestamp): "); if (is_null[3]) fprintf(stdout, " NULL\n"); else fprintf(stdout, " %04d-%02d-%02d %02d:%02d:%02d (%ld)\n", ts.year, ts.month, ts.day, ts.hour, ts.minute, ts.second, length[3]); fprintf(stdout, "\n"); /* Validate rows fetched */ fprintf(stdout, " total rows fetched: %d\n", row_count); if (row_count!= 2) fprintf(stderr, " MySQL failed to return all rows\n"); exit(0); /* Free the prepared result metadata */ mysql_free_result(prepare_meta_result); /* Close the statement */ 第 72 页

77 成都天心悦高科技发展有限公司 if (mysql_stmt_close(stmt)) fprintf(stderr, " failed while closing the statement\n"); fprintf(stderr, " %s\n", mysql_stmt_error(stmt)); exit(0); mysql_stmt_fetch_column() int mysql_stmt_fetch_column(mysql_stmt *stmt, MYSQL_BIND *bind, unsigned int column, unsigned long offset) 描述从当前结果集行获取 1 列 bind 提供了应将数据置于其中的缓冲 其设置方法应与设置 mysql_stmt_bind_result() 的相同 column 指明了将获取哪个列 第 1 列编号为 0 offset 是数据值内的偏移量, 将从该处开始检索数据 可将其用于获取碎片形式的数据值 值开始部分的偏移量为 0 返回值如果成功获取了值, 返回 0 如果出现错误, 返回非 0 值 错误 CR_INVALID_PARAMETER_NO Invalid column number. CR_NO_DATA 已抵达结果集的末尾 mysql_stmt_field_count() unsigned int mysql_stmt_field_count(mysql_stmt *stmt) 描述为语句处理程序返回关于最近语句的行数 对于诸如 INSERT 或 DELETE 等不生成结果集的语句, 该值为 0 通过调用 mysql_stmt_prepare() 准备好了语句后, 可调用 mysql_stmt_field_count() 返回值表示结果集中行数的无符号整数 错误无 mysql_stmt_free_result() 描述 my_bool mysql_stmt_free_result(mysql_stmt *stmt) 第 73 页

78 数字有机体工作库及大规模存储与管理系统开发手册 释放与执行预处理语句生成的结果集有关的内存 对于该语句, 如果存在打开的光标, mysql_stmt_free_result() 将关闭它 返回值如果成功释放了结果集, 返回 0 如果出现错误, 返回非 0 值 错误 mysql_stmt_init() MYSQL_STMT *mysql_stmt_init(mysql *mysql) 描述创建 MYSQL_STMT 句柄 对于该句柄, 应使用 mysql_stmt_close(mysql_stmt *) 释放 返回值成功时, 返回指向 MYSQL_STMT 结构的指针 如果内存溢出, 返回 NULL 错误 CR_OUT_OF_MEMORY 内存溢出 mysql_stmt_insert_id() my_ulonglong mysql_stmt_insert_id(mysql_stmt *stmt) 描述返回预处理 INSERT 或 UPDATE 语句为 AUTO_INCREMENT 列生成的值 在包含 AUTO_INCREMENT 字段的表上执行了预处理 INSERT 语句后, 使用该函数 返回值为在执行预处理语句期间自动生成或明确设置的 AUTO_INCREMENT 列返回值, 或由 LAST_INSERT_ID(expr) 函数生成的值 如果语句未设置 AUTO_INCREMENT 值, 返回值不确定 错误无 mysql_stmt_num_rows() my_ulonglong mysql_stmt_num_rows(mysql_stmt *stmt) 描述返回结果集中的行数 mysql_stmt_num_rows() 的用法取决于是否使用了 mysql_stmt_store_result() 来对语句句柄中的全部结果集进行了缓冲处理 如果使用了 mysql_stmt_store_result(), 可立刻调用 mysql_stmt_num_rows() 第 74 页

79 成都天心悦高科技发展有限公司 返回值结果集中的行数 错误无 mysql_stmt_param_count() unsigned long mysql_stmt_param_count(mysql_stmt *stmt) 描述返回预处理语句中参数标记符的数目 返回值表示语句中参数数目的无符号长整数 错误无 示例 : 关于 mysql_stmt_param_count() 的用法, 请见 mysql_stmt_execute() 中给出的示例 mysql_stmt_param_metadata() MYSQL_RES *mysql_stmt_param_metadata(mysql_stmt *stmt) 该函数目前不做任何事 描述返回值错误 mysql_stmt_prepare() int mysql_stmt_prepare(mysql_stmt *stmt, const char *query, unsigned long length) 描述给定 mysql_stmt_init() 返回的语句句柄, 准备字符串查询指向的 SQL 语句, 并返回状态值 字符串长度应由 length 参量给出 字符串必须包含 1 条 SQL 语句 不应为语句添加终结用分号 ( ; ) 或 \g 通过将问号字符? 嵌入到 SQL 字符串的恰当位置, 应用程序可包含 SQL 语句中的一个或多个参数标记符 标记符仅在 SQL 语句中的特定位置时才是合法的 例如, 它可以在 INSERT 语句的 VALUES() 列表中 ( 为行指定列值 ), 或与 WHERE 子句中某列的比较部分 ( 用以指定比较值 ) 但是, 对于 ID( 例如表名或列名 ), 不允许使用它们, 不允许指定二进制操作符 ( 如等于号 = ) 的操作数 后一个限制是有必要的, 原因在于, 无法确定参数类型 第 75 页

80 数字有机体工作库及大规模存储与管理系统开发手册 一般而言, 参数仅在 DML( 数据操作语言 ) 语句中才是合法的, 在 DDL( 数据定义语言 ) 语句中不合法 执行语句之前, 必须使用 mysql_stmt_bind_param(), 将参数标记符与应用程序变量绑定在一起 返回值如果成功处理了语句, 返回 0 如果出现错误, 返回非 0 值 错误 CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令 CR_OUT_OF_MEMORY 内存溢出 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_SERVER_LOST 查询过程中, 与服务器的连接丢失 CR_UNKNOWN_ERROR 出现未知错误 如果准备操作失败 ( 即 mysql_stmt_prepare() 返回非 0 值 ), 可通过调用 mysql_stmt_error() 获取错误消息 示例 : 关于 mysql_stmt_prepare() 的用法, 请见 mysql_stmt_execute() 中给出的示例 mysql_stmt_reset() my_bool mysql_stmt_reset(mysql_stmt *stmt) 描述在客户端和服务器上, 将预处理语句复位为完成准备后的状态 主要用于复位用 mysql_stmt_send_long_data() 发出的数据 对于语句, 任何已打开的光标将被关闭 要想重新准备用于另一查询的语句, 可使用 mysql_stmt_prepare() 返回值如果语句成功复位, 返回 0 如果出现错误, 返回非 0 值 错误 CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_SERVER_LOST 查询过程中, 与服务器的连接丢失 第 76 页

81 成都天心悦高科技发展有限公司 CR_UNKNOWN_ERROR 出现未知错误 mysql_stmt_result_metadata() MYSQL_RES *mysql_stmt_result_metadata(mysql_stmt *stmt) 描述如果传递给 mysql_stmt_prepare() 的语句能够生成结果集,mysql_stmt_result_metadata() 将以指针的形式返回结果集元数据, 该指针指向 MYSQL_RES 结构, 可用于处理元信息, 如总的字段数以及单独的字段信息 该结果集指针可作为参量传递给任何基于字段且用于处理结果集元数据的 API 函数, 如 : mysql_num_fields() mysql_fetch_field() mysql_fetch_field_direct() mysql_fetch_fields() mysql_field_count() mysql_field_seek() mysql_field_tell() mysql_free_result() 完成操作后, 应释放结果集结构, 可通过将其传递给 mysql_free_result() 完成 它与释放通过 mysql_store_result() 调用获得的结果集的方法类似 mysql_stmt_result_metadata() 返回的结果集仅包含元数据, 不含任何行结果 与 mysql_stmt_fetch() 一起使用语句句柄, 可获取行 返回值 MYSQL_RES 结果结构 如果不存在关于预处理查询的任何元信息, 返回 NULL 错误 CR_OUT_OF_MEMORY 内存溢出 CR_UNKNOWN_ERROR 出现未知错误 示例 : 关于 mysql_stmt_result_metadata() 的用法, 请见 mysql_stmt_fetch() 中给出的示例 mysql_stmt_row_seek() MYSQL_ROW_OFFSET mysql_stmt_row_seek(mysql_stmt *stmt, MYSQL_ROW_OFFSET offset) 描述 第 77 页

82 数字有机体工作库及大规模存储与管理系统开发手册 将行光标设置到语句结果集中的任意行 offset 值是行偏移的值, 行偏移应是从 mysql_stmt_row_tell() 或 mysql_stmt_row_seek() 返回的值 该值不是行编号, 如果打算按编号查找结果集中的行, 可使用 mysql_stmt_data_seek() 取而代之 该函数要求结果集结构包含查询的全部结果, 以便 mysql_stmt_row_seek() 能够仅与 mysql_stmt_store_result() 一起使用 返回值行光标的前一个值 可以将该值传递给后续的 mysql_stmt_row_seek() 调用 错误无 mysql_stmt_row_tell() MYSQL_ROW_OFFSET mysql_stmt_row_tell(mysql_stmt *stmt) 描述返回针对前一个 mysql_stmt_fetch() 的行光标的当前位置 该值可用作 mysql_stmt_row_seek() 的参量 仅应在 mysql_stmt_store_result() 之后使用 mysql_stmt_row_tell() 返回值行光标的当前偏移量 错误无 mysql_stmt_send_long_data() my_bool mysql_stmt_send_long_data(mysql_stmt *stmt, unsigned int parameter_number, const char *data, unsigned long length) 描述允许应用程序分段地 ( 分块 ) 将参数数据发送到服务器 可以多次调用该函数, 以便发送关于某一列的字符或二进制数据的不同部分, 列必须是 TEXT 或 BLOB 数据类型之一 parameter_number 指明了与数据关联的参数 参数从 0 开始编号 data 是指向包含将要发送的数据的缓冲区的指针, length 指明了缓冲区内的字节数 注释 : 自上一个 mysql_stmt_execute() 或 mysql_stmt_reset() 后, 对于与 mysql_stmt_send_long_data() 一起使用的所有参数, 下一个 mysql_stmt_execute() 调用将忽略绑定缓冲 如果希望复位 / 忽略已发送的数据, 可使用 mysql_stmt_reset() 返回值如果成功地将数据发送到服务器, 返回 0 如果出现错误, 返回非 0 值 错误 第 78 页

83 成都天心悦高科技发展有限公司 CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_OUT_OF_MEMORY 内存溢出 CR_UNKNOWN_ERROR 出现未知错误 示例 : 在下面的示例中, 介绍了以信息块形式为 TEXT 列发送数据的方法 它会将数据值 DosSQL, 最流行的开放源码数据库 插入到 text_column 列中 假定 mysql 变量具有有效的连接句柄 #define INSERT_QUERY "INSERT INTO test_long_data(text_column) VALUES(?)" MYSQL_BIND bind[1]; long length; smtt = mysql_stmt_init(mysql); if (!stmt) fprintf(stderr, " mysql_stmt_init(), out of memory\n"); exit(0); if (mysql_stmt_prepare(stmt, INSERT_QUERY, strlen(insert_query))) fprintf(stderr, "\n mysql_stmt_prepare(), INSERT failed"); fprintf(stderr, "\n %s", mysql_stmt_error(stmt)); exit(0); memset(bind, 0, sizeof(bind)); bind[0].buffer_type= MYSQL_TYPE_STRING; bind[0].length= &length; bind[0].is_null= 0; /* Bind the buffers */ if (mysql_stmt_bind_param(stmt, bind)) fprintf(stderr, "\n param bind failed"); fprintf(stderr, "\n %s", mysql_stmt_error(stmt)); exit(0); 第 79 页

84 数字有机体工作库及大规模存储与管理系统开发手册 /* Supply data in chunks to server */ if (!mysql_stmt_send_long_data(stmt,0,"mysql",5)) fprintf(stderr, "\n send_long_data failed"); fprintf(stderr, "\n %s", mysql_stmt_error(stmt)); exit(0); /* Supply the next piece of data */ if (mysql_stmt_send_long_data(stmt,0," - The most popular Open Source database",40)) fprintf(stderr, "\n send_long_data failed"); fprintf(stderr, "\n %s", mysql_stmt_error(stmt)); exit(0); /* Now, execute the query */ if (mysql_stmt_execute(stmt)) fprintf(stderr, "\n mysql_stmt_execute failed"); fprintf(stderr, "\n %s", mysql_stmt_error(stmt)); exit(0); mysql_stmt_sqlstate() const char *mysql_stmt_sqlstate(mysql_stmt *stmt) 描述对于由 stmt 指定的语句,mysql_stmt_sqlstate() 返回由 Null 终结的字符串, 该字符串包含针对最近调用预处理语句 API 函数的 SQLSTATE 错误代码, 该函数或成功或失败 错误代码由 5 个字符构成 "00000" 表示 无错误 这些值由 ANSI SQL 和 ODBC 指定 注意, 并非所有的 MySQL 错误均会被映射到 SQLSTATE 代码 值 "HY000"( 一般错误 ) 用于未映射的错误 返回值包含 SQLSTATE 错误代码 由 Null 终结的字符串 mysql_stmt_store_result() 描述 int mysql_stmt_store_result(mysql_stmt *stmt) 第 80 页

85 成都天心悦高科技发展有限公司 对于成功生成结果集的所有语句 (SELECT SHOW DESCRIBE EXPLAIN), 而且仅当你打算对客户端的全部结果集进行缓冲处理时, 必须调用 mysql_stmt_store_result(), 以便后续的 mysql_stmt_fetch() 调用能返回缓冲数据 对于其他语句, 没有必要调用 mysql_stmt_store_result(), 但如果调用了它, 也不会造成任何伤害或导致任何性能问题 通过检查 mysql_stmt_result_metadata() 是否返回 NULL, 可检测语句是否生成了结果集 注释 : 默认情况下, 对于 mysql_stmt_store_result() 中的所有列,MySQL 不计算 MYSQL_FIELD->max_length, 这是因为, 计算它会显著降低 mysql_stmt_store_result() 的性能, 而且大多数应用程序不需要 max_length 如果打算更新 max_length, 可通过调用 mysql_stmt_attr_set(mysql_stmt, STMT_ATTR_UPDATE_MAX_LENGTH, &flag) 启用它 返回值如果成功完成了对结果的缓冲处理, 返回 0 如果出现错误, 返回非 0 值 错误 CR_COMMANDS_OUT_OF_SYNC 以不恰当的顺序执行了命令 CR_OUT_OF_MEMORY 内存溢出 CR_SERVER_GONE_ERROR MySQL 服务器不可用 CR_SERVER_LOST 在查询过程中, 与服务器的连接丢失 CR_UNKNOWN_ERROR 出现未知错误 C API 预处理语句方面的问题 下面列出了一些目前已知的与预处理语句有关的问题 : TIME TIMESTAMP 和 DATETIME 不支持秒部分, 例如来自 DATE_FORMAT() 的秒部分 将整数转换为字符串时, 在某些情况下, 当 MySQL 不打印前导 0 时, 可与预处理语句一起使用 ZEROFILL 例如, 与 MIN(number-with-zerofill) 一起 将浮点数转换为客户端中的字符串时, 被转换值最右侧的位可能会与原始值的有所不同 预处理语句不使用查询高速缓冲, 即使当查询不含任何占位符时也同样 第 81 页

86 数字有机体工作库及大规模存储与管理系统开发手册 多查询执行的 C API 处理 DosSQL 支持在单个查询字符串中指定的多语句的执行 要想与给定的连接一起使用该功能, 打开连接时, 必须将标志参数中的 CLIENT_MULTI_STATEMENTS 选项指定给 mysql_real_connect() 也可以通过调用 mysql_set_server_option(mysql_option_multi _STATEMENTS_ON), 为已有的连接设置它 在默认情况下,mysql_query() 和 mysql_real_query() 仅返回第 1 个查询的状态, 并能使用 mysql_more_results() 和 mysql_next_result() 对后续查询的状态进行处理 /* Connect to server with option CLIENT_MULTI_STATEMENTS */ mysql_real_connect(..., CLIENT_MULTI_STATEMENTS); /* Now execute multiple queries */ mysql_query(mysql,"drop TABLE IF EXISTS test_table;\ CREATE TABLE test_table(id INT);\ INSERT INTO test_table VALUES(10);\ UPDATE test_table SET id=20 WHERE id=10;\ SELECT * FROM test_table;\ DROP TABLE test_table"); do /* Process all results */... printf("total affected rows: %lld", mysql_affected_rows(mysql));... if (!(result= mysql_store_result(mysql))) printf(stderr, "Got fatal error processing query\n"); exit(1); process_result_set(result); /* client function */ mysql_free_result(result); while (!mysql_next_result(mysql)); 多语句功能可与 mysql_query() 或 mysql_real_query() 一起使用 它不能与预处理语句接口一起使用 按照定义, 预处理语句仅能与包含单个语句的字符串一起使用 日期和时间值的 C API 处理 二进制协议允许你使用 MYSQL_TIME 结构发送和接受日期和时间值 (DATE TIME DATETIME 和 TIMESTAMP) 要想发送临时数据值, 可使用 mysql_stmt_prepare() 创建预处理语句 然后, 在调用 m ysql_stmt_execute() 执行语句之前, 可采用下述步骤设置每个临时参数 : 1. 在与数据值相关的 MYSQL_BIND 结构中, 将 buffer_type 成员设置为相应的类型, 该类型指明了发送的临时值类型 对于 DATE TIME DATETIME 或 TIMESTAMP 值, 第 82 页

87 成都天心悦高科技发展有限公司 将 buffer_type 分别设置为 MYSQL_TYPE_DATE MYSQL_TYPE_TIME MYSQL_TYPE _DATETIME 或 MYSQL_TYPE_TIMESTAMP 2. 将 MYSQL_BIND 结构的缓冲成员设置为用于传递临时值的 MYSQL_TIME 结构的地址 3. 填充 MYSQL_TIME 结构的成员, 使之与打算传递的临时值的类型相符 使用 mysql_stmt_bind_param() 将参数数据绑定到语句 然后可调用 mysql_stmt_execut e() 要想检索临时值, 可采用类似的步骤, 但应将 buffer_type 成员设置为打算接受的值的类型, 并将缓冲成员设为应将返回值置于其中的 MYSQL_TIME 结构的地址 调用 mysql_ stmt_execute() 之后, 并在获取结果之前, 使用 mysql_bind_results() 将缓冲绑定到语句上 下面给出了一个插入 DATE TIME 和 TIMESTAMP 数据的简单示例 假定 mysql 变量具有有效的连接句柄 MYSQL_TIME ts; MYSQL_BIND bind[3]; MYSQL_STMT *stmt; strmov(query, "INSERT INTO test_table(date_field, time_field,timestamp_field) VALUES(?,?,?"); stmt = mysql_stmt_init(mysql); if (!stmt) fprintf(stderr, " mysql_stmt_init(), out of memory\n"); exit(0); if (mysql_stmt_prepare(mysql, query, strlen(query))) fprintf(stderr, "\n mysql_stmt_prepare(), INSERT failed"); fprintf(stderr, "\n %s", mysql_stmt_error(stmt)); exit(0); /* set up input buffers for all 3 parameters */ bind[0].buffer_type= MYSQL_TYPE_DATE; bind[0].buffer= (char *)&ts; bind[0].is_null= 0; bind[0].length= 0; bind[1]= bind[2]= bind[0]; mysql_stmt_bind_param(stmt, bind); /* supply the data to be sent in the ts structure */ 第 83 页

88 数字有机体工作库及大规模存储与管理系统开发手册 ts.year= 2002; ts.month= 02; ts.day= 03; ts.hour= 10; ts.minute= 45; ts.second= 20; mysql_stmt_execute(stmt); C API 线程函数介绍 当你打算创建线程客户端时, 需要使用下述函数 my_init() void my_init(void) 描述调用任何 MySQL 函数之前, 需要在程序中调用该函数 它将初始化 MySQL 所需的某些全局变量 如果你正在使用线程安全客户端库, 它还能为该线程调用 mysql_thread_init() 通过 mysql_init() mysql_library_init() mysql_server_init() 和 mysql_connect(), 可自动调用该函数 返回值无 mysql_thread_init() my_bool mysql_thread_init(void) 描述对于每个创建的线程, 需要调用该函数来初始化与线程相关的变量 它可由 my_init() 和 mysql_connect() 自动调用 返回值如果成功, 返回 0, 如果出现错误, 返回非 0 值 mysql_thread_end() void mysql_thread_end(void) 描述调用 pthread_exit() 来释放 mysql_thread_init() 分配的内存之前, 需要调用该函数 注意, 该函数不会被客户端库自动调用, 必须明确调用它以避免内存泄漏 第 84 页

89 成都天心悦高科技发展有限公司 返回值 无 mysql_thread_safe() unsigned int mysql_thread_safe(void) 描述该函数指明了客户端是否编译为线程安全的 返回值如果客户端是线程安全的, 返回 1, 否则返回 创建客户端程序 如果你编译了自己编写的 MySQL 客户端, 或编译了从第三方获取的 MySQL 客户端, 必须在链接命令中使用 -lmysqlclient -lz 选项链接它们 你或许还应指定 -L 选项, 通知链接程序到哪里找到库 例如, 如果将库安装到了 /usr/local/mysql/lib, 可在链接命令中使用 sr/local/mysql/lib -lmysqlclient lz 对于使用 MySQL 头文件的客户端, 编译它们时还须指定 -I 选项 ( 例如, -I/usr/local/mysql/include), 以便编译器能找到头文件 为了使在 Unix 平台上编译 MySQL 程序变得简单, 提供了 config 脚本 你也可以使用它来编译 MySQL 客户端, 如下所述 : CFG=/usr/local/mysql/bin/ config sh -c "gcc -o progname `$CFG --cflags` progname.c `$CFG --libs`" 需要使用 sh c, 使得 shell 不将 config 的输出当作 1 个词对待 编程示例 为了满足广大用户的开发需求, 让用户能够快速使用 DosSQL 的 C API 进行编程, 这里提供了一些基础的示例 示例程序可以在安装目录 /usr/local/dossql/demo/ 内找到 在使用这些示例之前, 您务必先要阅读 README 文件, 以获知如何使用这些示例 示例程序已经以 gcc 和 g++ 编译通过, 并且采用 make 编译工具进行编译, 具体细节可以通过阅读 Makefile 文件得知 测试编程示例默认使用数据库用户名为 root, 密码为空 3.2 Perl API 简介 DBI 是很多数据库的一个通用接口, 即使用户只编写一个脚本, 不用改变也能工作于 很多数据库引擎 每一种数据库类型需要相应地定义一种数据库驱动程序 (DBD) PerlDBI 为数据库应用开发人员 数据库前台工具开发人员提供了一种标准的应用程序设计接口, 第 85 页

90 数字有机体工作库及大规模存储与管理系统开发手册 使开发人员可以用 Perl 语言编写完整的数据库应用程序 特别地, 由于 CAPI 接口经修改后通过服务器端运行的调度程序可以实现对数据库出现故障时的故障恢复, 这样也就保证了 PerlDBI 在数据库出现故障时的高可用性 Perl DBI 模块为数据库访问提供了一个通用接口, 能够编写无需更改就能与不同的数据库引擎一起工作的 DBI 脚本 要想使用 DBI, 必须安装 DBI 模块, 并为打算访问的每种服务器安装数据库驱动程序 (DBD) 模块 对于 MySQL, 该驱动程序是 DBD::mysql 模块 Perl DBI 是推荐的 Perl 接口, 它取代了旧的名为 mysqlperl 的接口,mysqlperl 已过时 DBI 信息能够在命令行上提供, 也能以在线方式提供, 或采用印刷形式 : 一旦安装了 DBI 和 DBD::mysql 模块, 可使用 perldoc 命令在命令行上获取关于它们的信息 : shell> perldoc DBI shell> perldoc DBI::FAQ shell> perldoc DBD::mysql 也可以使用 pod2man pod2html 等将这类信息转换为其他格式 关于 Perl DBI 的在线信息, 请访问 DBI 网站, 该站点还提供了 1 个一般性 DBI 邮件列表 至于印刷版信息, 官方的 DBI 书籍是编程 Perl DBI(Alligator Descartes 和 Tim Bunce,O'Reilly & Associates, 2000) 关于该书的信息, 请访问 DBI 网站 详细使用说明 Perl 语言用于方法返回值的变量有这些含义 : $dbh 数据库句柄 $sth 语句句柄 $rc 返回代码 ( 经常是一个状态 ) $rv 返回值 ( 经常是一个行数 ) 常用的 DBI 方法如下 : connect 建立到一个数据库服务器的连接 disconnect 断开数据库服务器的连接 prepare 准备执行一个 SQL 语句 execute 执行准备好的语句 do 准备并执行一个 SQL 语句 quote 加引号于要插入的字符串或 BLOB 值 fetchrow_array 作为一个字段数组取出下一行 fetchrow_arrayref 作为一个字段的引用数组取出下一行 fetchrow_hashref 作为一个哈希表的引用取出下一行 fetchall_arrayref 作为一个字段数组取出所有数据 finish 完成一条语句并且让系统释放资源 rows 返回受影响的行数 第 86 页

91 成都天心悦高科技发展有限公司 data_sources ChopBlanks NUM_OF_PARAMS NULLABLE trace 返回可在 localhost 上得到的数据库的数组控制 fetchrow_* 方法是否剥去空格在准备的语句中的占位 (placeholder- 参数 ) 的数目其列可以是 NULL 执行调试跟踪 connect 使用 connect 方法使得一个数据库连接到数据源 $data_source 值应该以 DBI:driver_name: 开始 以 DBD::MYSQL 驱动程序使用 connect 的例子 : $dbh = DBI->connect("DBI:MYSQL:$database", $user, $password); $dbh = DBI->connect("DBI:MYSQL:$database:$hostname", $user, $password); $dbh = DBI->connect("DBI:MYSQL:$database:$hostname:$port", $user, $password); 如果用户名或口令未定义,DBI 分别使用 DBI_USER 和 DBI_PASS 环境变量的值 如果不指定主机名, 它缺省为 'localhost' 如果不指定一个端口号, 缺省端口为 (3306) 对 Msql-DosSQL-modules 版本 ,$data_source 值允许某些修饰词 : mysql_read_default_file=file_name 读取作为一个选项文件的 filename mysql_read_default_group=group_name 当读取选项文件时的缺省组通常是 [client] 组 通过指定 mysql_read_default_group 选项, 缺省组变成 [group_name] 组 mysql_compression=1 在客户和服务器之间使用压缩通信 mysql_socket=/path/to/socket 指定用于与服务器连接的 Unix 套接字的路径名 可以给出多个修饰词 ; 每一个必须前置一个分号 例如, 如果想要避免在一个 DBI 脚本中硬编码用户名和口令, 可以从用户的 ~/.my.cnf 选项文件中取出它们, 而不是这样编写的 connect 调用 : $dbh = DBI->connect("DBI:MYSQL:$database". ";mysql_read_default_file =$ENVHOME/.my.cnf", $user, $password); 这个调用将读取在选项文件中为 [client] 组而定义的选项 如果想做同样的事情, 但是也使用为 [perl] 组指定的选项, 可以使用 : $dbh = DBI->connect("DBI:MYSQL:$database". ";mysql_read_default_file= $ENVHOME/.my.cnf". ";mysql_read_default_group=perl", $user, $password) disconnect disconnect 方法从数据库断开数据库句柄 它一般就在从程序退出之前被调用 范例 $rc = $dbh->disconnect; 第 87 页

92 数字有机体工作库及大规模存储与管理系统开发手册 prepare 准备一条由数据库引擎执行的 SQL 语句并且返回语句句柄 ($sth), 可以使用它调用 execute 方法 一般地借助于 prepare 和 execute 来处理 SELECT 语句 ( 和类 SELECT 语句, 例如 SHOW DESCRIBE 和 EXPLAIN) 范例 : $sth = $dbh->prepare($statement) or die "Can't prepare $statement: $dbh->errstr\n"; execute execute 方法执行一个准备好的语句 对非 SELECT 语句,execute 返回受影响的行数 如果没有行受影响,execute 返回 "0E0",Perl 将它视为零而不是真 对于 SELECT 语句, execute 只是在数据库中启动 SQL 查询 ; 需要使用在下面描述的 fetch_* 方法之一检索数据 范例 : $rv = $sth->execute or die "can't execute the query: $sth->errstr; do do 方法准备执行一条 SQL 语句并且返回受影响的行数 如果没有行受到影响,do 返回 "0E0",Perl 将它视为零而不是真 这个方法通常用于事先无法准备好 ( 由于驱动程序的限制 ) 或不需要执行多次 ( 插入 删除等等 ) 的非 SELECT 语句 范例 : $rv = $dbh->do($statement) or die "Can't execute $statement: $dbh- >errstr\n"; quote quote 方法被用来 转义 包含在 string 中的任何特殊字符并增加所需的外部的引号 范例 : $sql = $dbh->quote($string) fetchrow_array 这个方法取下一行数据并且作为一个字段值数组返回它 范例 : while(@row = $sth->fetchrow_array) print qw($row[0]\t$row[1]\t$row[2]\n); fetchrow_arrayref 这个方法取下一行数据并且作为对一个字段值数组的引用返回它 范例 : while($row_ref = $sth->fetchrow_arrayref) print qw($row_ref->[0]\t$row_ref->[1]\t$row_ref->[2]\n); 第 88 页

93 成都天心悦高科技发展有限公司 fetchrow_hashref 这个方法取一行数据并且返回包含字段名 / 值对的一个哈希表的引用 这个方法不如使用上述数组引用那样有效 范例 : while($hash_ref = $sth->fetchrow_hashref) print qw($hash_ref->firstname\t$hash_ref->lastname\t\ $hash_ref- > title\n); fetchall_arrayref 这个方法被用来获得从 SQL 语句返回的所有数据 ( 行 ) 它返回一个数组的引用, 该数组包含对数组的每行的引用 用一个嵌套循环来存取或打印数据 范例 : my $table = $sth->fetchall_arrayref or die "$sth->errstr\n"; my($i, $j); for $i ( 0.. $#$table ) for $j ( 0.. $#$table->[$i] ) print "$table->[$i][$j]\t"; print "\n"; finish 表明将没有更多的数据从这个语句句柄取出 调用这个方法可释放语句句柄和任何与它相关的系统资源 范例 : $rc = $sth->finish; rows 返回由最后一条命令改变 ( 更新 删除等 ) 的行数 这通常用在非 SELECT 的 execute 语句之后 范例 : $rv = $sth->rows; NULLABLE 返回一个对布尔值数组的引用 ; 对数组的每个成员,TRUE 值表示该列可以包含 NULL 值 范例 : 第 89 页

94 数字有机体工作库及大规模存储与管理系统开发手册 $null_possible = $sth->nullable; NUM_OF_FIELDS 这个属性表明由一条 SELECT 或 SHOW FIELDS 语句返回的字段数目 可以用它检查一条语句是否返回了结果 : 零值表明一个象 INSERT DELETE 或 UPDATE 的非 SELECT 语句 范例 : $nr_of_fields = $sth->num_of_fields; data_sources 这个方法返回一个数组, 它包含在主机 'localhost' 上的 DosSQL 服务器可得到的数据库名 范例 = DBI->data_sources("DosSQL"); ChopBlanks 这个属性确定 fetchrow_* 方法是否将去掉返回值的头和尾的空白 范例 : $sth->'chopblanks' =1; trace trace 方法开启或关闭跟踪 当作为一个 DBI 类方法调用时, 它影响对所有句柄的跟踪 当作为一个数据库或语句句柄方法调用时, 它影响对给定句柄的跟踪 ( 和句柄的未来子孙 ) 设置 $trace_level 为 2 以提供详细的踪迹信息, 设置 $trace_level 为 0 以关闭跟踪 踪迹输出缺省地输出到标准错误输出 如果指定 $trace_filename, 文件以添加模式打开并且所有跟踪的句柄的手被写入该文件 范例 : DBI->trace(2);# trace everything DBI->trace(2,"/tmp/dbi.out"); # trace everything to /tmp/dbi.out $dth->trace(2); # trace this database handle $sth->trace(2); # trace this statement handle 也可以通过设置 DBI_TRACE 环境变量开启 DBI 跟踪 将它设置为等价于调用 DBI->(value) 的数字值, 将它设置为等价于调用 DBI->(2,value) 的路径名 3.3 PHP API PHP 是一种服务器端 HTML 嵌入式脚本处理语言, 可使用该语言创建动态网页 它 可用于大多数操作系统和 Web 服务器, 也能访问大多数常见数据库, 包括 MySQL PHP 可以作为单独程序运行, 也能编译为模块, 用于 Apache Web 服务器 第 90 页

95 成都天心悦高科技发展有限公司 PHP 分发版和文档均能从 PHP 网站获得 3.4 Python API MySQLdb 为 Python 提供了 MySQL 支持, 它符合 Python DB API 版本 2.0 的要求, 可 在 上找到它 3.5 Tcl API MySQLtcl 是一种简单的 API, 用于从 Tcl 编程语言访问 MySQL 数据库服务器, 可在 上找到它 第 91 页

96 数字有机体工作库及大规模存储与管理系统开发手册 4 连接器 4.1 DosODBC 简介 ODBC( 开放式数据库连接性 ) 为客户端程序提供了访问众多数据库或数据源的一种方式 ODBC 是标准化的 API, 允许与 SQL 数据库服务器进行连接 它是根据 SQL Access Group 的规范开发的, 它定义了一套函数调用 错误代码和数据类型, 可将其用于开发独立于数据库的应用程序 通常情况下, 当需要数据库独立或需要同时访问不同的数据源时, 将用到 ODBC DosODBC 是 DosSQL 提供的 Windows 平台 ODBC 连接器 在 ODBC 机制下, 用户可以通过应用程序直接存取 DosSQL 数据库 用户通过 DosODBC 访问 DosSQL, 是基于 DosSQL 提供的 Windows 平台 ODBC 驱动程序实现的 DosODBC 是在 Windows95 和 Windows NT 上的一个 ODBC 与 C API 间的接口, 借助该接口并利用 DosSQL 的 C API 接口, 使 DosSQL 对用户提供的服务更具可用性 可靠性和稳定性 安装执行 DosODBC exe 进行安装 详细使用说明 ODBC 数据源的配置 配置步骤如下 : 第一步 : 进入控制面板的管理工具, 打开管理工具中的数据源 (ODBC); 第二步 : 点击 ODBC 数据源管理器 的 用户 DSN 和 系统 DSN, 若没有 DosSQL ODBC 3.51 Driver 驱动程序则点击 添加, 选定驱动程序后点击 完成, 若已有该驱动程序这步即可省略 ; 第三步 : 选定驱动程序所在的 用户数据源 或 系统数据源 的 名称, 点击 配置, 在弹出的对话框中分别填写如下内容 : Data Source Name: 数据源名称 Description: 数据源名称说明 Host/Server Name(or IP): 已注册 DosSQL 服务的节点 ip Database Name: 默认连接数据库名 User: 用户名 Password: 用户密码 Port: 默认端口号为 3306 最后点击 OK 即完成 ODBC 数据源的配置 第 92 页

97 成都天心悦高科技发展有限公司 使用步骤 通过 MyODBC 使用 DosSQL 的步骤简述如下 : 第一步 : 在 Windows 的 Vserver 中加入已注册的活动 DosSQL 服务器 ip, 若不添加, 则该 ip 为默认 ip; 第二步 : 配置 ODBC 数据源, 尽量填写正确 ip( 第一步和第二步顺序可交换 ); 第三步 : 编译 执行用户应用程序 4.2 JDBC JDBC 简介 JDBC 是用 Java 语言实现的与 DosSQL 数据库进行连接的 API 接口 JDBC 为数据库应用开发人员 数据库前台工具开发人员提供了一种标准的应用程序设计接口, 使开发人员可以用纯 Java 语言编写完整的数据库应用程序 JDBC 主要负责与数据库进行连接 向数据库发送 SQL 语句 处理数据库返回的结果 特别地, 该 JDBC 基于 mysql-connector-java 进行了修改, 通过服务器端运行的调度程序实现对数据库出现故障时的故障恢复, 保证 JDBC 在数据库出现故障时的高可用性 安装将 dossql-connector-java jar 驱动文件存放到 java 编译器的 lib 目录下并修改 java 运行环境配置文件, 即可以在进行 java 语言的 JDBC 开发中使用 ( 详细配置请参见 java 编程手册 ) 详细使用说明应用程序调用 JDBC API 访问数据库管理系统是通过以下五个步骤来实现的 : 1) 加载特定的 JDBC 驱动程序为了与特定的数据源连接,JDBC 必须加载相应的驱动程序 我们提供的 JDBC 需要使用的是 "com.mysql.jdbc.driver" 该驱动程序是通过语句 :Class.forName("DriverName"); 来加载的, 即 Class.forName("com.mysql.jdbc.Driver") 2) 用已注册的驱动程序建立到数据库管理系统的连接我们要做的第二步是用已经注册的驱动程序建立到数据库管理系统的连接, 这要通过 DriverManager 类的 getconncetion 方法来实现 具体使用以下两行代码 : String url="jdbc:dossql://localhost/database"; Connection con=drivermanager.getconnection(url,user,password); 这里特别需要注意的是 String 类型 url 参数的取值,url 代表一个将要连接的特定的数据库管理系统的数据源 GetConnection() 方法只有一个参数 String url, 代表 JDBC 数据源, 一般需要三个参数 :String url Strng user String password User 和 password 代表数据库管理系统的用户名和口令 第 93 页

98 数字有机体工作库及大规模存储与管理系统开发手册 如果连接成功, 则会返回一个 Connection 类的对象 con 以后对数据库的操作都是建立在 con 对象的基础上 GetConnection() 方法是 DriverManager 类的静态方法, 使用时不用生成 DriverManager 类的对象, 直接使用类名 DriverManager 就可以调用 3) 创建 Statement 声明, 执行 SQL 语句在实例化一个 Connection 类的对象 con, 成功建立一个到数据库管理系统的连接之后 我们要做的第三步是利用该 con 对象生成一个 Statement 类的对象 stmt 该对象负责将 SQL 语句传递给数据库管理系统执行, 如果 SQL 语句产生结果集,stmt 对象还会将结果集返回给一个 ResultSet 类的对象 (ResultSet 类将在下一节做详细介绍 ) Statement 类的主要方法有三个 : executeupdate(string sql) executequery(string sql) execute(string sql) executeupdate(string sql) 方法用于执行 DDL 类型的 SQL 语句, 这种类型的 SQL 语句会对数据库管理系统的对象进行创建 修改 删除操作, 一般不会返回结果集 executequery(string sql) 方法用于执行一条查询数据库的 SELECT 语句 如果有符合查询条件的数据存在, 该方法将返回一个包含相应数据的 ResultSet 类对象, 否则该对象的 next() 方法将返回 false execute(string sql) 方法用于执行一个可能返回多个结果集的存储过程 (Stored Procedure) 或者一条动态生成的不知道结果集个数的 SQL 语句 如果存储过程或者 SQL 语句产生一个结果集, 该方法返回 false 如果产生多个结果集, 该方法返回 true 我们可以综合运用 Statement 类的 getresultset(), getupdatecount(), getmoreresults() 方法来检索不同的结果集 4) 关闭 Statement 对象 Statement 对象在打开后可以多次调用 executequery(string sql) executeupdate(string sql) execute(string sql) 方法来执行 SQL 语句, 与数据库管理系统进行交互 但一个 Statement 对象在同一时间只能打开一个结果集, 对第二个结果集的打开隐含着对第一个结果集的关闭 如果想对多个结果集同时进行操作, 必须创建多个 Statement 对象, 在每个 Statement 对象上执行 SQL 语句获得相应的结果集 5) 关闭 Connection 对象在处理完对数据库的操作后, 一定要将 Connection 对象关闭, 以释放 JDBC 占用的系统资源 在不关闭 Connection 对象的前提下再次用 DriverManager 静态类初始化新的 Connection 对象会产生系统错误 而一个已经建立连接的 Connection 对象可以同时初始化多个 Statement 对象 JDBC 使用总体介绍 JDBC 的准确定义应该是两组, 分别面向应用程序开发人员和数据库驱动程序开发人 员的两组 API(Application Programming Interface), 以及将前者向后者转化的内在封装逻辑 其中, 面向应用程序开发人员的接口为 JDBC API, 也就是 sun 公司免费提供的各个版本的 第 94 页

99 成都天心悦高科技发展有限公司 JDK 在包 java.sql.* 中定义的一系列类 (Class) 接口(Interface) 异常(Exception) 以及这些类和接口中定义的属性 (property) 和方法 (method) 面向数据库驱动程序开发人员的接口为 JDBC Driver API, 这些 API 是提供给各个数据库管理系统的生产厂家的 在包 java.sql.* 中定义的一系列类中最重要的有 : java.sql.drivermanager 用来加载不同的 JDBC 驱动程序并且为创建新的数据库连接提供支持 ; java.sql.connection 完成对某一指定数据库的连接功能 ; java.sql.statement 在一个已经创建的连接 (java.sql.connection) 中作为执行 SQL 语句的容器 ; 它包含了两个重要的子类 : 1) java.sql.preparedstatement 用于执行预编译的 SQL 语句 ; 2) java.sql.callablestatement 用于执行数据库中已经创建好的存储过程 java.sql.result 代表特定 SQL 语句执行后的数据库结果集 以上这些类是编写 JAVA 应用程序经常要调用的, 类之间的关系如图 4-1 所示, 随后将对这些类的使用做详尽的阐述 本手册中未详细说明的部分接口的用法请参照 JDBC3.0API 标准参考手册 图 4-1 JDBC API 结构关系图 基本操作 1) 对表中记录的操作对一个表中的记录可以进行修改 插入 和删除操作, 分别对应于 SQL 的 UPDATE INSERT DELETE 操作 同 SELECT 操作类似,executeUpdate 方法的参数也是一个 String 对象, 代表将要执行的进行更新操作的 SQL 语句 ExecuteUpdate() 方法的返回值不是一个 ResultSet 对象, 而是一个整数 对于 UPDATE INSERT DELETE 操作, 这个整数是操作所有有影响的记录的行数 对于其他不返回值的 SQL 语句, 例如,CREATE TABLE,ALTER TABLE,DROP TABLE 等,executeUpdate() 的返回值是零 我们看下面的语句 : String sql= UPDATE Sales SET total= 6000 WHERE id= ; 第 95 页