【国家标准(GB)】 移动数据库应用编程接口规范

ICS35.060
中华人民共和国国家标准
GB/T 20531-2006
移动数据库应用编程接口规范
APl specification for mobile database2006-09-18发布
中华人民共和国国家质量监督检验检疫总局中国国家标准化管理委员会
2007-03-01实施
规范性引用文件
术语、定义、缩略语和符号
术语和定义
缩略语
数据类型
5数据类型说明
语法规则
访问规则
一般规则
数据库级的操作
DBCreate
DBOpen
DBClose
DBDrop
SQI.操作函数·
SQLAllocHandle
SQL.Prepare
SQLBindParameter
SQLColAteribute
SQLColCounl
SQLExeeutc
SQLExecDirect
SQLRowCount
SQLBindCol
SQLSetCursorPos
SQLFetch
SQLGetData
SQLFreeHandle
I+上AE
HKNKAca
GB/T 20531—2006
GB/T20531-2006
8同步连接级.…
8.1 SYNCOpen
8.2 SYNCGetPara
8.3SYNCGo
8. 4SYNCCtose
9差错信息的代码.
一般差错
内存差错.
文件差错-
句柄差错
数据库差错
表差错
索引差错
9.8指针差错
列访问差错·
行级差错
参考文献
本标准由中华人民共和国信息产业部提出。本标谁由信息产业部电子工业标准化研究所归口。ikoNiKca
GB/T20531—2006
本标准起草单位：中国人民大学数据与知识工程研究所、北京人大金仓信息技术有限公司。本标准主要起草人：张孝、王珊、张文亮。面
GB/T20531—2006
移动数据库是嵌人式系统软件的重要组成部分，它主要用来对移动设备端的数据进行安全、方便、商效的管理，并负责与中心的主机数据库进行数据的同步。过移动数据库的客户端SQL接口，可以实现对移动数据库中数据的直接存取；而使用数据尚步编程接口，应用可以完成移动数据库和指定的中心主机数据库的同步，保持数据库的全局一致性和完整性。本标准仅定义了对移动数据库中各种对象（包括数据库本身、表，案引)进行操作的接口。移动数据库引擎支持的SQL为移动数据库应用对数据库中数据的存取提供了很好的支持,但本标推没有明确规定数据库引擎的操作能力，这屉于移动数据库SQL标准应该规定的内容不在接口标谁的范畴。GB/T12991规定了数据语言QL的实现标准，移动数据库引擎在S实现点可以将其作为引用标推之一。对移动数据库成用籍程接口需言，接口议要求所访问的数据库引有SQL支持能力，但SQL支持的具体实现可以由据供者确定。本标准还规定了对库本身操作和同步连接操作的规范接口。本标准是为应用管理移动数据库中数据所需接口制定的规范，而不是移动数据库引擎的实现标准或替代标准
本标准使用的SQL语言可以是标准SQL语言或替动数据库引葬提供的扩展SQL语言，这取决于移动数据库引擎的实现。
1范围
移动数据库应用编程接口规范
HiiKAoNiKAca
GB/T 20531—2006
本标推规定了嵌人式移动数据库产品应提供的应用缩程接口，确定了该类数据库产品中设计应用编程接口的一般原则。
本标推适用于按照GB/T12991开发的移动数据库系统或通用数据库系统的嵌人式版本的设计、实现、测试,升级等过程。
2规范性引用文件
下列文件中的条款通过本标准的引用而成为本标准的条款：凡是注日期的引用文件，其随后所有的修改单（不包括谢误的内容）或修订版均不适用于本标推，然而，鼓励根据本标推达成协议的各方研究是否可使用这些文件的最新版本。凡是不注日期的引用文件，其最新版本适用于本标准GB/T7108—1994数据元和交换格式信息交换日期和时间表示法（eqV1SO8601：1988）GB/T 12991信息处理系统数据库语言 SQL(GB/T 12991—1991,idtIS0/1EC9075：1989）ISO/[EC 9075-2数据库语言SQL第2部分：基础ISO/IEC9075-3数据库语言SQL第3部分：调用级接口（SQI/C1.)3术语，定文，缩略语和符号
GB/T12991确立的以及下列术语、定义、缩略语和符号适用于本标准。3.1术语和定义
字特串长度length of character string本标准中提及的字符串的长度都是包括串结束符”0的长度。3.1.2
常盘 coustant
系统中具有固定值的符号序列。3.1.3
标度scale
辩点型数据中小数部分的长度或位数。3.1.4
syntartic elements
语法元素
描述应用编程接口规格的必要元素。3.1.5
语法syntax
说明接函数的定义格式。
参致parameter
说明接口函数中的参数的数据类型和意义。1
GB/T 20531--2006
返回值 return value
说明接口函数执行后返回结果的可能值。3.1.8
功能 functionality
说明接口函数的用途。
酱注remarks
说明接口函数使用中需要注意的特殊尚题，3.1.10
error diagnosties message
差错诊断信息
说明当函数调用出错时，应再编程接口报告的消息串，用来帮助调用者识别差错、判断原因或者进行差错处理。
3.2缩略语
ApplicationPrograrnmingInterface应用编程接口File Desgriptor
Mohile Database
Mobile, Database System
3.3符号
本标推规定的语法中使用的符号说明如下：小括号中的元素为函数的参数。用做语旬结康符。
用于分随函数的参数。
文件播述符
移动数据库
移动数据库系统
用做产生式规则中的定义符，被定义的元紧出现在符号的左边，而定义该元素的公式出现在.
右边。
指明方括号中独元素是可选的。公式中括号内的部分可以被显式指明或省略。4概念
4.1句柄
按接 ISO/IEC 9075-3 的规定,向病是指向内存对象或资源的指针。在调用:MDB API 分配数据库资源时，MDBS通过接口将该指针返回给谢用者，从而使得调用者可以通过句柄访问MDBS所分配的资源。
根据句柄所指向的资源的不同，移动数据所中的句柄分为一类，分别是：数据库句柄、语句句柄和同步连接句柄。嵌入式应用可以通过不同的函数分配这三类句柄，并利用这些句柄对数据库、语句执行结果及同步连接进行控制和操作，这三类句柄描述如下：a）数据库句柄
标识每一个打开的数据库。数据库句柄指向一-个内存结构，该内存结构中包含对数据库进行操作的一些必要信息，例如：
1）DBFD:打开的数据库文件的文件描述符；STMTSPTR：数据库句柄,上创建的所有语句句柄的指针数组，数组元素的数目依赖于提2)5
供商的设计！
3）数据库句柄指向的结构中包含的其他扩展信息。b）语句句柄
HiiKAoNiKAca
CB/T20531—2006
标识了一个准备执行或已经执行的语句,语句句辆指向的内存结构中包含执行该语句的一些必要信息。如：
DBHANDLE：该语句的执行对象所在的数据库的库句柄；2）PARAPTR：指向语句中的参数的指针（见7.3)。维护每个参数所需要的信息，如参数内部标识、参数类型、参数数目等具体信息格式由提供商给出，但不能影响应用的可移植性；
3）RFSUI.TSETPTR：指向语句的执行结果（见7.6,7.7）。结果集合中的数据可以通过相应的接口函数访间；
4）语句句柄指尚的结构中包含的其他扩展信息。)连接句柄
标识移动客户与服务器之间每一个打开的同步连接。连接句柄指向一个内存结构，该内存结构中包含进行同步连接操作的一些必要信息，例如：1）DBHANDLE：该语句的执行对象所在的数据库的句柄；2）CONNFD打开的同步连接描述符。例如，Socket方式下CONNFD为套接字文件描述符，串口方式下为串口描述符等3）PARAPTR：措向控制同步操作的参数的措针。维护同步过程中数据传输所要的控制信息和日志信息等，如连率控制、超时、缓冲区等；4）连接句摘指向的结构中包含的其他扩展信息。4.2数据类型
数据类型是移动数据库系统中可表示值的集台。值的逻辑表示是<字值。值的物理表示依赖于实现。
在本标谁中，值是初等项，对其不再做逻细分。值或是空值，或是非空慎。空值是依赖于实现的特殊值，它不间于相关数据类型的所有非空值。实际上只有一个空值，且这个值是所有数据类型的一个成员。空值不存在(字值)，即使在某些位置使用关键字 NULL指明要一个空值。
SQL用下列<关键字>定义和命名不同的数据类型：BLOB、CHAR、VARCHAR、INTEGER、LONG,FLOATDATE,DATETIME、NUMERIC、TEXT.派生的数据类型有CHARPTR,INTPTR,HANDLE。每个数据类型的语义特性在第5章中描述。每个数据类型都有一个相关的数据类型描述符。数据类型描述符的内容由它所描述的特定数据类型决定。数据类型描述符包括数据类型标志和描述该数据类型实例的特性所需的全部信息。4.3常虽
本标准定义了以下符号常：
MDB_SUCCESS执行成功返回
MDB_ERR
4.4结构
执行失败返回
结构是由不同或相同数据类型的数据组成的架合。本标准定义下列结构：
a) MDBCOMMPARA
功能：
说明同步连接通信信息的通信方式下的参数配置，如Sacket方式，串口方式等 spcket方式下需要提供：
SERNAME
主机服务器名
GB/T 20531—2006
其他扩展信息
其他扩展方式
其他扩展内容
MDBSYNCINFO
功能：
服务器[P地址
服务器要连接的端口号
说明每次同步的配置信息。保证移动应用能够和服务器主机数据库系统正确同步。该结构中包含的内容：
APPNAME
USERNAME
PASSWORD
OBJECT
其他扩展内容
c） MUBCA
功能：
应用名
用户名
用户在应用中的密码
籍要进行同步的同步对象名
移动数据库通信区（Communication Area)，记录每饮数据库操作后的执行状态。该结构中包含的内：
MDBERRCODE
操作执行后的差错信息的代码。只有当接口返回MDB_ERR时，它的值才有意义。
其他扩展内容
如果结构名带PTR后缀则表示对应结构的指针。5数据类型说明
5.1功能
指明数据类型。本标推所应用的数据类型如果未给出附加的说明或限定，则应遵循GB/T12991和ISO/IEC9075-2中对相应数据类型所做的规定。5.2格式
本规范所用数据类型定义的产生式格式为：（数据类型》：1=《字符申类型>[<数值类型》（日期时间类型）<文本类型》（指针类型）(字符串类型>：:－CHAR[(左括号)长度)(右括号)VARCHAR(左括号》(长度>(右括号）《数值类型）！：NUMER[C［左括号）<精度>L（返号）标度）右据号）IINTEGERINT
IFLOAT[<左括号）《精度》（右括号）ILONG
（长度)：：=无符号整数）
（精度）：一（无符号整数）
(标度)：:=无符号整数）
（日期时间类型）：：=DATE|DATETIME(文本类型):=TEXT BLOF
<指针类型)::=CHARPTR IINTPTRIHANDLE(左括号):1=(
(右括号)：一）
5.3语法规则
使用上面的产生式语法声明有效数据类型时要遵循下面的语法规则：a）《长度)或<精度>的值应该大于0；b）如果省丢了（长度>则默认(长度>为 1;如果省去了《精度),则默认为实现定义的<精度)；d)
如果省去了《标度),则默认(标度)为口;HiiKAoNiKAca
GB/T 20531-2006
NUMERIC指明数据类型是精确数值，具有<精度和(标度>所指明的十进制精度和标度,而且(标度>必须小于或等于《精度）；f）INTEGER或INT指明数据类型是精确数值，具有一进制或十进制精度和Q标度，选择二进制或十进制精度是实现定义的；
FLOAT指明数据类型是近似数值，具有等于或大于指明的<精度)值的二进制精度。（精度)g
的最大值是实现定义的,《精度不应该大于这个值：h)
TEXT是一种没有长度限制的宁符类型。最大长度依赖丁移动数据库引擎的实现：CHARPTR是指向CHAR的指针！
INTPTR是指向INTEGER的指针：
k）HANDLE是接口使用程序中的可变类型，真实类型依赖于移动数据库引擎的实现。5.4访问规则
5.5一般规则
本标准使用数据类型的一股规则包括：a）（日期时间类型}应包含（日期时闻字段)的年，月日、时分秒GB/T7408-1994规定了口期时间的使用说明，表1指明日期时川数据类型中（日期时间字b)
段)值的约束以满足定义 API 的要求。表1日期时间项中字段有效值
关链词
MINUTE
SECOND
6数据库级的操作
月期时间字段的有效值
0001到9999
01到12
在 1 到 31 的范围内,但按照格林历已形成的日期规则,义受 MDNTH和YEAR字段值的进一步约束
00到23
00到59
00到59.9指明的数字个数移动数据库提供的是一种数据容器，独立于它管理的具体数据，一股应用在移动设备和嵌人系统中，因此也称作嵌人式数据库、嵌人式移动数据库等。不同的应用可以共享数据，也可以使用独立的数据。支持多库是现代数据库技术的一个基本特点，系统需要提供必要的数据库级管理功能。本标准的这部分函数主要实现对数据库本身的操作，包括创建、打开、关闭和删除数据库。6.1DBCreate
INTEGER DBCreatel
GB/T 20531-2006
CHARPTR DhPathName
INTEGER DbSize);
DbPathName输入
DbSize
返回值
要创建的数据库名学
要创建的数据库的大小，实现者可以指定默认值如果成功返国MI)H_SUCCESS;如果失败返回MDB_ERR。功能
创建具有指定名字的数据库，该数据库名字可以在以后打开数据库时使用。用法
数据库名含路径名。
差错诊断信息
如果返回值为MDB_ERR，通过读取MDBCA中的MDBERRCDDE确定出错原因。6.2 DBOpen
INTEGER DBOpen(www.bzxz.net
HANDLE DbHandle,
CHARPTRIhPathName);
DhHandle
DbPathName 轮人
返回值
数据库句柄
要打开的数据库的名字
如果成功返回MDB_SUCCESS；如果失败返回MDB_ERR功能
打开具有指定名字的数据库，执行成功后在DbHandle中保存使用的数据库句柄。用法
数据库名含路径名。
差错诊断信息
如果返回值为MDB_ERR，通过读取MDBCA中的MDBERRCODE确定出错原因。6.3DBClase
INTEGER DBClose(
HANDLE DhHandle):
DbHandle输人数据库句柄
返回值
如果成功返回 MDB_SUCCESS;如果失败返回 MDB_ERR。功能
释放相关参数缓冲区，关闭数据库。用法
无特殊说明。
差错诊断信息
如果返回值为 MDB_ERR，通过读取MDBCA中的 MDBERRCODE确定出错原因。6
6.4 DBDrop
INTEGERDBDrop
CHARPTR DbPathName);
DbPathNatme输人要删除的数据库名返回值
如果成功返回MDB_SUCCESS；如果失败返回MDB.ERR功能
翻除其有指定名的数据库。
数据库名含路径名。指定数搁库必须先关闭，然后才能把它删除。差错诊断信息
HiiKAoNiKAca
GB/T 20531—2006
如果返回值为 MDB_ERR,通过读取 MDBCA中的 MDBERRCODE确定出错原因。7SQL操作函数
如果对数据库中对象的访间可以通过SQL来完成，那么应用程序需要调用该部分接口函数来完成。
本标准中该类API函数的主要功能是执行SQL语句，获取查询语句执行结果。7. 1 SQLAllocHandle
INTEGERSQLAIlocHandler
HANDLE DbHandle.
HANDLE SQLHandle
DbHandle
SQLHandle
返回值
数据库句柄
分配的语句句柄，指向内存中已经分配的一个数据结构缓冲区如果成功则返回 MDH_SUCCESS,如果失嫩返回 HDB_ERR。功能
分配语句句柄。
该函数分配的语句句柄用于对DbHandle对应的数据库进行操作，执行该函数之前，必须已经将该函数要操作的数据库打开,其句柄为 DbHandle。差错诊断倍息
如果 [NT 返回值为 MDB_ERR,通过读取 MDBCA 中的 MDBERRCODE确定出错原因。7.2SQLPrepare
INTEGER SQI.Preparel
HANDLE SQLHandle,
CHARPTR SQLText,
INTEGER SQLTextLen,
小提示：此标准内容仅展示完整标准里的部分截取内容，若需要完整标准请到上方自行免费下载完整标准文档。