1、ICS 35.060 L 78 吗暨中华人民共和国国家标准GB/T 20531-2006 移动数据库应用编程接口规范API specification for mobile database 2006-09-18发布中华人民共和国国家质量监督检验检茂总局中国国家标准化管理委员会2007-03-01实施发布前言. . , , . 引盲1 范围-2 规范性引用文件3 术语、定义、缩略语和符号. . . . . . . 3. 1 术语和定义. . . . . . 3.2 缩略语3.3 符号. 4 概念. 4. 1 句柄. 4.2 数据类型. . . . . 4. 3 常量. 4.4 结构. 5 数据
2、类型说明-5. 1 功能. 5. 2 格式5. 3 语法规则5.4 访问规则. . . . . 5. 5 一般规则. 6 数据库级的操作6. 1 DBCreate . 6.2 DBOpen 6.3 DBClose 6.4 DBDrop 7 SQL操作函数7. 1 SQLAllocHandle 7. 2 . SQLPrepare . 7. 3 SQLBindParameter . 7. 4 SQLColAttribute 7. 5 SQLColCount . 7. 6 SQLExecute . . 7. 7 SQLExecDirect 7. 8 SQLRowCount. 7. 9 SQLBind
3、Col 7.10 SQLSetCursorPos 7. 11 SQLFetch 7.12 SQLGetData . 7. 13 SQLFreeHandle . GB/T 20531-2006 目次E N l l 1 2 2 2 2 3 3 3 4 4 4 5 5 5 5 5 6 6 7 7 7 7 8 8 9 9 10 10 11 11 11 12 12 I GBjT 20531-2006 8 同步连接级. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 8. 1 SYNCOpen 13
4、8. 2 SYNCGetPara闺. . . . . . . . . 1. . . . . 13 8.3 SYNCGo 14 8. 4 SYNCClose 14 9 差错信息的代码. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 9. 1 一般差错. . I . . . . . . . . . . . . . . . . . . . . . . . 15 9. 2 内存差错. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .,. .
5、. . . . . . 15 9. 3 文件差错159.4 句柄差错. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 9. 5 数据库差错. . . . . . . 9. 6 表差错. . . . . . . . I . . I . . . . . . . . . . . . . . . . . . . . . 15 9. 7 索引差错9. 8 指针差错. . . . . . . . . . . . .
6、. . . . . . . . . . . . . . . . . ., ., . . . 15 9. 9 列访问差错9. 10 行级差错. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I . H 参考文献E GB/T 20531-2006 . _._ 目U吕本标准由中华人民共和国信息产业部提出。本标准由信息产业部电子工业标准化研究所归口。本标准起草单位:中国人民大学数据与知识工程研究所、北京人大金仓信息技术有限公司。本标准主要起草人:张孝、王珊、张文亮。皿GB/T 20531-2006 sl 移动数据库是嵌入式系
7、统软件的重要组成部分，它主要用来对移动设备端的数据进行安全、方便、高效的管理，并负责与中心的主机数据库进行数据的同步。通过移动数据库的客户端SQL接口，可以实现对移动数据库中数据的直接存取;而使用数据同步编程接口，应用可以完成穆动数据库和指定的中心主机数据库的同步，保持数据库的全局一致性和完整性。本标准仅定义了对移动数据库中各种对象(包括数据库本身、表、索引)进行操作的接口。移动数据库引擎支持的SQL为移动数据库应用对数据库中数据的存取提供了很好的支持，但本标准没有明确规定数据库引擎的操作能力，这属于移动数据库SQL标准应该规定的内容而不在接口标准的范畴。GB/T 12991规定了数据库语言S
8、QL的实现标准，移动数据库引擎在SQL实现上可以将其作为引用标准之一。对移动数据库应用编程接口而言，接口仅要求所访问的数据库引擎有SQL支持能力，但SQL支持的具体实现可以由提供者确定。本标准还规定了对库本身操作和同步连接操作的规范接口p本标准是为应用管理移动数据库中数据所需接口制定的规范，而不是移动数据库引擎的实现标准或替代标准。本标准使用的SQL语言可以是标准SQL语言或移动数据库引擎提供的扩展SQL语言，这取决于移动数据库引擎的实现。N GB(T 20531-2006 移动数据库应用编程接口规范1 范围本标准规定了嵌入式移动数据库产品应提供的应用编程接口，确定了该类数据库产品中设计应用编
9、程接口的一般原则自本标准适用于按照GB/T12991开实现、测试、升级等过程。2 规范性引用文件3 术语、定GB/T 1 3. 1 术语和3. 1. 1 字符串长本标准中3. 1.2 常量系统中具有固3. 1. 3 标度scale 浑点型数据中小数部主3. 1. 4 语法元素syntactic elements 描述应用编程接口规格的必要元素。3. 1. 5 语i去syntax说明接口函数的定义格式。3. 1. 6 参数parameter 说明接口函数中的参数的数据类型和意义。系统或通用数据库系统的嵌人式版本的设计、一飞期的引用文件，其随后所有准达成协议的各方研究9075:1989) 1 GB
10、/T 20531-2006 3. 1. 7 返回值return value 说明接口函数执行后返回结果的可能值。3. 1. 8 功能functionality 说明接口函数的用途。3. 1. 9 备注remarks 说明接口函数使用中需要注意的特殊问题。3. 1. 10 差错诊断信息error diagnostics msage 说明当函数调用出错时，应用编程接口报告的消息串，用来帮助调用者识别差错、判断原因或者进行差错处理。3.2 铺路i吾API Application Programming Interface FD File Descriptor MDB Mobile Database
11、应用编程接口文件描述符移动数据库MDBS Mobile Database System 3. 3 符号移动数据库系统本标准规定的语法中使用的符号说明如下10 小括号中的元素为函数的参数。J 用做语句结束符。用于分隔函数的参数。用做产生式规则中的定义符，被定义的元素出现在符号的左边，而定义该元素的公式出现在右边。指明方括号中的元素是可选的。公式中括号内的部分可以被显式指明或省略。4 概念4. 1 旬柄按ISO/IEC9075-3的规定，句柄是指向内存对象或资掘的指针。在调用MDBAPI分配数据库资掘时，MDBS通过接口将该指针返回给调用者，从而使得调用者可以通过句柄访问MDBS所分配的资掘。根据
12、句柄所指向的资掘的不同，移动数据库中的句柄分为三类，分别是:数据库句柄、语句句柄和同步连接句柄。嵌入式应用可以通过不同的函数分配这三类句柄，并利用这些句柄对数据库、语句执行结果及同步连接进行控制和操作，这三类句柄描述如下:2 a) 数据库句柄标识每一个打开的数据库。数据库句柄指向一个内存结构，该内存结构中包含对数据库进行操作的一些必要信息，例如:1) DBFD:打开的数据库文件的文件描述符;2) STMTSPTR:数据库句柄上创建的所有语句句柄的指针数组，数组元素的数目依赖于提供商的设计;3) 数据库句柄指向的结构中包含的其他扩展信息。b) 语句句柄G/T 20531-2006 标识了一个准备
13、执行或已经执行的语句，语句句柄指向的内存结构中包含执行该语句的一些必要信息。如:1) DBHANDLE:诙语句的执行对象所在的数据库的库句柄;2) PARAPTR:指向语句中的参数的指针(见7.3)。维护每个参数所需要的信息，如参数内部标识、参数类型、参数数目等具体信息格式由提供商给出，但不能影响应用的可移植性;3) RESUL TSETPTR:指向语句的执行结果(见7.6，7.7)。结果集合中的数据可以通过相应的接口函数访问;4) 语句句柄指向的结构中包含的其他扩展信息。c) 连接句柄标识移动客户与服务器之间每一个打开的同步连接。连接句柄指向一个内存结构，该内存结构中包含进行同步连接操作的一
14、些必要信息，例如z1) DBHANDLE:诙语句的执行对象所在的数据库的句柄;2) CONNFD:打开的同步连接描述符。例如，Socket方式下CONNFD为套接字文件描述符，串口方式下为串口描述符等;3) PARAPTR:指向控制同步操作的参数的指针。维护同步过程中数据传输所需要的控制信息和日志信息等，如速率控制、超时、缓冲区等;的连接句柄指向的结构中包含的其他扩展信息。4.2 数据类型数据类型是移动数据库系统中可表示值的集合。值的逻辑表示是字值)。值的物理表示依赖于实现。在本标准中，值是初等项，对其不再做逻辑细分。值或是空值，或是非空值。空值是依赖于实现的特殊值，它不同于相关数据类型的所有
15、非空值。实际上只有一个空值，且这个值是所有数据类型的一个成员。空值不存在宇值，即使在某些位置使用关键字NULL指明需要一个空值。SQL用下列关键字定义和命名不同的数据类型:BLOB、CHAR、VARCHAR、INTEGER、LONG、FLOAT、DATE、DATETIME、NUMERIC、TEXTo生的数据类型有CHARPTR，INTPTR, HANDLE。每个数据类型的语义特性在第5章中描述。每个数据类型都有一个相关的数据类型描述符。数据类型描述符的内容由它所描述的恃定数据类型决定。数据类型描述符包括数据类型标志和描述该数据类型实例的特性所需的全部信息。4.3 常量本标准定义了以下符号常量:
16、MDB_SUCCESS执行成功返回MDB_ERR 执行失败返回4.4 结构结构是由不同或相同数据类型的数据组成的集合。本标准定义下列结构za) MDCOMMPARA 功能:说明同步连接通信信息的通信方式下的参数配置，如Socket方式，串口方式等socket方式下需要提供zSERNAME 主机服务器名3 GBjT 20531-2006 SERIP PORT 其他扩展信息其他扩展方式其他扩展内容b) MDBSYNCINFO 功能:服务器IP地址服务器要连接的端口号说明每次同步的配置信息。保证移该结构中包含的内容:APPNAME 应用USERNAME 阻卢名PASSWORD OBJECT 其他扩展
17、c) MDBCA 功能:移动数该结构中其他如果结构5 数据类型说明5. 1 功能指明数据类型。1和ISO/IEC9075号5. 2 格式本规市所用数据类(数据类型12=(字符串类型):=CH 数值类型):= NUMERI IINTEGERI IFLOAT，贝u默认标度为0;的NUMERIC指明数据类型是精确数值，具有精度和标度所指明的十进制精度和梅度，而且标度必细小于或等于精度); f) INTEGER或INT指明数或十进制精度是实现定g) FLOAT指明数据类的最大值是实h) k) HANDLE 5.4 访问规则元。5.5 -般规则本标准使用b) GB/T 7 段)值的DAY HOUR MI
18、NUTE SECOND 6 数据库辑的操作十进制精度和0标度，选择二进制精度示由时间小数秒精度指明的数字个数移动数据库提供的是一种数据容器，强立于它管理的具体数据，一般应用在移动设备和嵌入系统中，因此也称作嵌入式数据库、嵌入式移动数据库等。不同的应用可以共享数据，也可以使用独立的数据。支持多库是现代数据库技术的一个基本特点，系统需要提供必要的数据库级管理功能。本标准的这部分函数主要实现对数据库本身的操作，包括创建、打开、关闭和删除数据库。6. 1 DBCreate 语法INTEGER DBCreate( 5 GB/T 20531-2006 CHARPTR DbPathName INTEGER
19、DbSize) ; 参数DbPathName 输入DbSize 输入返回值要创建的数据库名字要创建的数据库的大小，实现者可以指定默认值如果成功返回MDB一SUCCESS;如果失败返回MDB_ERR.功能创建具有指定名字的数据库，该数据库名字可以在以后打开数据库时使用。用法数据库名含路径名。差错诊断信息如果返回值为MDB甲ERR，通过读取MDBCA中的MDBERRCODE确定出错原因。6.2 DBOpen 语法INTEGER DBOpen( HANDLE DbHandle, CHARPTR DbPathName) ; 参数DbHandle 输出DbPathName输入返回值数据库句柄要打开的数据
20、库的名字如果成功返回MDB_SUCCESS;如果失败返回MDB_ERR。功能打开具有指定名字的数据库，执行成功后在DbHandle中保存使用的数据库句柄。用法数据库名含路径名。差错诊断信息如果返回值为MDB_ERR，通过读取MDBCA中的MDBERRCODE确定出错原因。6.3 DBClose 6 语法INTEGER DBClose( HANDLE DbHandle) : 参数DbHandle输入数据库句柄返回值如果成功返回MDB_SUCCESS;如果失败返回MDB_ERR.功能释放相关参数蟹冲区，关闭数据库。用法无特殊说明。差错诊断信息如果返回值为MDB_ERR，通过读取MDBCA中的MDB
21、ERRCODE确定出错原因。GB/T 20531-2006 6.4 DBDrop 语法INTEGER DBDrop( CHARPTR DbPathName) ; 参数DbPathName输入要删除的数据库名返回值如果成功返回MDB_SUCCESS;如果失败返回MDB_ERRo功能删除具有指定名的数据库。用法数据库名含路径名。指定数据库必须先关闭，然后才能把它删除。差错始断信息如果返回值为MDB_ERR，通过读取MDBCA中的MDBERRCODE确定出错原困。7 SQL操作函数如果对数据库中对象的访问可以通过SQL来完成，那么应用程序需要调用该部分接口函数来完成。本标准中该类API函数的主要功能
22、是执行SQL语句，获取查询语句执行结果。7. 1 SQLAllocHandle i普法-INTEGER SQLAllocHandleC 参散DbHandle 输人SQLHandle 揄出返回值HANDLE DbHandle, HANDLE SQLHandle 数据库句柄分配的语句句柄，指向内存中已经分配的一个数据结掏缓冲区如果成功则返回MDB_SUCCESS;如果失败返回HDB一ERRo功能分配语句句柄。用法该函数分配的语句句恫用于对DbHandle对应的数据库进行操作，执行该函数之前，必须已经将该函数要操作的数据库打开，其句柄为DbHandleo差错诊断信息如果INT返回值为MDB_ERR，
23、通过读取MDBCA中的MDBERRCODE确定出错原因。7. 2 SQLPrepare 语法INTEGER SQLPrepare( HANDLE SQLHandle , CHARPTR SQLText, INTEG ER SQL TextLen, 7 GB/T 20531-2006 7.3 参数INTPTR SQL Type SQLHandle 输入SQLText 输入语句句柄要执行的SQL语句SQL语句的长度SQLTextLen 输入SQLType 输出SQL语句类型，主要用于区分是查询语句还是非查询语句返回值功能语法参数如果成功返回MDB_SUCCESS准备一个要执行的SQLHandle
24、ParaNum ParaBuf ParaBufType ParaBufLen 输入返回值如果成功则返回MDB_S功能将指定类型的数据缓冲区绑定到指定查询语句中的位置参数。用法可以完成语句的语错原因。，该函数将绑定到语句参数的应用程序变量的地址填写到语句句柄的相应项中。差错诊断信息如果返回值为MDB_ERR，通过读取MDBCA中的MDBERRCODE确定出错原因。7. 4 SQLColAttribute i吾;法INTEGER SQLColAttribute( B GBjT 20531-2006 参数SQLHandle 输入Coll、Jum输入ColName 输出ColType ColLen C
25、olScale HANDLE SQLHandl巴，INTEGER Colr、um，CHARPTR ColName , INTPTR ColType , INTPTR ColLen, INTPTR ColScale) ; 返回值功能参数如果成功返SQLHandle ColCount 语句句柄SQL吾句执行结果中的列数返回值如果成功返回MDB一飞功能返回指定查询输出的结果集用法只有当SQLHandle指向的是个SELECT类型的语句句柄时可用。差错诊断信息如果返回值为MDB_ERR，通过读取MDBCA中的MDBERRCODE确定出错原因。7.6 SQLExecute i吾法INTEGER SQLE
26、xecute( HANDLE SQLHandJe) ; 参数SQLHandle 输入要执行的SQL吾句的句柄9 GB/T 20531-2006 返回值如果成功返回MDB_SUCCESS;如果失败返回MDB_ERR。功能使用语句中当前已经绑定的参数，执行已经准备好的语句。用法必拥在SQLPrapre之后执行，如果语句为查询语句，执行后结果集的信息将填写到语句句柄中的相应结果集缓冲区。差错诊断信息如果返回值为MDB_ERR，通过读取MDBCA中的MDBERRCODE确定出错原因。7. 7 SQLExecDirect 语法参数INTEG ER SQLExecDirect ( SQLHandle 输入
27、SQLText 输入SQLTextLen 输入HANDLE SQLHandle, CHARPTR SQLText, INTEGER SQL TextLen) ; 语句句柄要执行的SQLt吾句要执行的SQL语句的长度返回值如果成功返回MDB_SUCCESS;如果失败返回MDB_ERRo功能不需要绑定任何参数，直接执行SQL语句。用法不需要进行准备。如果语句为查询语旬，将结果集的信息填写到语句句柄中的相应项口差错珍断信息如果返回值为MDB_ERR，通过读取MDBCA中的MDBERRCODE确定出错原因。7. 8 SQLRowCount 10 i吾1去参数INTEGER SQLRowCount( I
28、NTEGER SQLHandle, INTPTR RowCount); SQLHandle 输入SQL语句句柄RowCount 输出SQL语句执行结果集中的行数返回值如果成功返回MDB_SUCCESS;如果失败返回MDB_ERRo功能用法返回指定查询执行后的结果集的行数。只有SQLHandle指向的是一个SELECT类型的语句句柄时可用。结果集中所有行的编号从0开始。G/T 20531-2006 差错诊断信息如果返回值为MDB_ERR，通过读取MDBCA中的MDBERRCODE确定出错原因。7. 9 SQLindCol i吾j去INTEGER SQLBindCol( 参数SQLHandle 输
29、入ColNum 输入BufType 输入BufPtr 输入BufLen 输入返回值HANDLE SQLHandle, INTPTR ColN um , INTPTR BufType , CHARPTR BufP时，INTPTR BufLen) ; SQL语句句柄要绑定的列号，取值为0，表的列数一lJ区间的正整数缓冲区的数据类型指向缓冲区的指针以字节计算的缓冲区的长度如果成功返回MDB_SUCCESS;如果失败返回MDB_;ERRo功能将结果集中的指定列绑定到应用程序中的某个数据缓冲区。用法无特殊说明。差错诊断信息如果INT返回值为MDB_ERR，通过读取MDBCA中的MDBERRCODE确定出
30、错原因。7. 10 SQLSetCursorPos 语法参数INTEGER SQLSetCursorPos ( SQLHandle 输入RowNum 输入HANDLE SQLHandle, INTEGER RowNum ); SQL语句句柄结果集中的游标行号返回值如果成功返回MDB_SUCCESS;如果失败返回MDB_ERR。功能将结果集中的游标设定到某一行。用法无特殊说明。差错诊断信息如果返回值为MDBERR，通过读取MDBCA中的MDBERRCODE确定出错原因。7. 11 SQLFetch i吾i去INTEGER SQLFetch( 11 GBjT 20531-2006 HANDLE S
31、QLHandle) ; 参数SQLHandle 输入SQL吾句句柄返回值如果成功返回MDB_SUCCESS;如果失败返回MDB_ERRo功能取得结果集中的当前行的数据。用法执行SQLSetCursorPos定位带标行，并且通过执行SQLBindCoI将所有的列都绑定之后才能执行诙函数。如果没有进行游标定位语句执行后，如果有差错诠断信息如果返回值7.12 SQLGetData 语法参散Bur BufType BufLen RalLen 返回值如果成功返回功能取得指定的某行某列的数据用法无特殊说明。差错诊断信息如果返回值为MDB甲ERR，通过读取MDBCA中的MDBERRCODE确定出错原因。7.
32、 13 SQLFreeHandle 语法INTEGER SQLFreeHandleC 12 8 8.2 GB/T 20531-2006 参数同步连接组参数Sync SyncPa SyncCo 返回值如果成功返功能HANDLE SQLHandle) ; 输入要释放的语句句柄UCCESS;如果失败返回MDB一ER建立服务器与移用法无特殊说明。差错谚断信息如果INT返回值为MDB_ERR，通过读取MDBCA中的MDBERRCODE确定出错原因自SYNCGetPara 语法INTEGER SYNCGetPara( HANDLE SyncHandle, MDBC。如1MPARAPTR SyncCommP
33、ara 13 GB/T 20531一2006参数SyncHandle 输入SyncCommPara输出返回值同步句柄同步的通讯参数如果成功返回MDBSUCCESS;如果失败返回MDBERR，功能取得同步通讯参数。用法无特殊说明。差错诊断信息如果返回值为MDB_ERR，通过读取MDBCA中的MDBERRCODE确定出错原因。8.3 SYNCGo i吾i去INTEGER SYNCGo( HANDLE SyncHandle, MDBSYNCINFO SyncData) 参数SyncHandle 输入同步句柄SyncData 输入需要同步的信息堪回值如果成功返回MDB一SUCCESS;如果失败返回MD
34、B_ERR，功能执行数据同步。用法该函数的调用必须在执行完同步的初始化之后，同步过程中的故障和恢复对用户透明。差错珍断信息如果INT返回值为MDB_ERR，通过读取MDBCA中的MDBERRCODE确定出错原因。8. 4 SYNCClose i吾j去INTEGER SYNCClose( HANDLE SyncHandle) ; 参数SyncHandle 输入同步句柄返回值如果成功返回MDB_SUCCESS;如果失败返回MDB_ERR。功能释放该次同步所占用的内存空间，关闭一个同步对话。用法无特殊说明。差错诊断信息如果INT返回值为MDB_ERR，通过读取MDBCA中的MDBERRCODE确定出
35、错原因。9 差错信息的代码系统执行过程中如果出错，需要在系统的公共通信区MDBCA填写差错信息的代码MDBER-14 GB/T 20531-2006 RCODE。9. 1 一般差错MDB_GEN_ERR 一般差错系统没有给该差错定义差错代码，因此无法在MDBCA中填写差错代码。只能通过系统返回的错误消息来判断出错原因。9. 2 内存差错MDB_MEM_ERR 内存分配差错系统无法给指定的句柄分配内存空间。9.3 文件差错MDB_FILE_ERROO MDB_FILE_ERRO 1 MDB_FILE_ERR02 MDB_FILE_ERR03 MDB_ TB_ERR003 MDB TB ERR00
36、3 9. 7 索引差错MDB IX ERROOl MDB IX ERR002 MDB_IX_ERR003 9. 8 指针差错无效的数据库要创建要打开创建索引数目MDB_PTR_ERR 无效指针，输入参数为NULL9.9 列访问差错MDB一COL_ERROlMDB一COL_ERR02MDB_COL_ERR03 9. 10 行级差错MDB_RO矶T_ERR列数越界，小于0或者大于最大列数无效列名无效列类型行号越界15 GB/T 20531-2006 16 参考文献lJ 大金仓信息技术有限公司.(小金灵程序员手册2J IBM DB2 Everyplace Application Developmen
37、t Guide Version 7 Release 2 3J Microsoft ODBC Help 4J SQL Anywhere Studio 7. O. 3 documentation CON-zvmONH筒。华人民共和国家标准移动数据库应用编程接口规范国由lGB/T 20531-2006 9非中国标准出版社出版发行北京复兴门外三里河北街16号邮政编码:100045网址WW电话:6852394668517548 中国标准出版社秦皇岛印刷厂印刷各地新华书店经销a拎印张1.5字数35千字2007年3月第一次印刷开本880X 1230 1/16 2007年3月第一版定价20.00* 书号:155066 1-28990 J(j 如有印装差错由本社发行中心调换版权专有侵权必究举报电话:(010)68533533GB/T
