fastDB CLI

 

fastDB CLI (2006-05-19 16:32)

分类： fastDB翻译

Call level interface

前面介绍的接口提供了C++方便而且可靠的数据访问机制。但其有两个不足：

1．这是非常C++化的从而不能够用于其它语言

2．只适用于对数据库的本地连接（同属于一个系统）

下面说明的接口克服了这两个限制。采用了纯ANSI C函数集，因而利用其将任意的程序设计语言映射到fastdb是很容易实现的。客户端与服务器的连接通过socket（不论是本地的还是标准的TCP/IP sockets）.

当然这个接口比起C++接口来说不是那么友好并且易于出错，但这是灵活性的代价。所有的类型，常量和函数都在cli.h文件中声明。

fastdb提供了多线程服务器来处理客户端的CLI会话。可以在SubSQL工具中用start server 'HOST:PORT' <线程数> 命令来启动这个服务器。该服务器可以接受本地（在一个系统中）和全局的客户连接然后将线程池中的一个线程与一个连接黏附。线程池的大小由“线程数”参数控制。但如果有更多的主动连接服务器可以派生出超过制定数字的线程，。一个线程与一个客户黏附知道会话结束。如果一个线程异常中止，该客户所作的任何改变都将被回滚。服务器可以通过相应的stop server 'HOST:PORT'命令停止。

CLI functions return codes
Error code	Description
cli_ok	Succeful completion
cli_bad_address	Invalid format of server
cli_connection_refused	Connection with server could not be established
cli_bad_statement	Text of SQL statement is not correct
cli_parameter_not_found	Parameter was not found in statement -
cli_unbound_parameter	Parameter was not specified
cli_column_not_found	No sucj colunm in the table
cli_incompatible_type	Conversion between application and database type is not possible
cli_network_error	Connection with server is broken
cli_runtime_error	Error during query execution
cli_bad_descriptor	Invalid statement/session description
cli_unsupported_type	Unsupported type for parameter or colunm
cli_not_found	Record was not found
cli_not_update_mode	Attempt to update records selected by view only cursor
cli_table_not_found	There is no table with specified name in the database
cli_not_all_columns_specified	Insert statement doesn't specify values for all table columns
cli_not_fetched	cli_fetch method was not called
cli_already_updated	cli_update method was invoked more than once for the same record
cli_table_already_exists	Attempt to create existed table
cli_not_implemented	Function is not implemented

Supported types
Type	Description	Size
cli_oid	Object identifier	4
cli_bool	Boolean type	1
cli_int1	Timy interger type	1
cli_int2	Small interger type	2
cli_int4	Interger type	4
cli_int8	Big interger type	8
cli_real4	Single precision floating point type	4
cli_real8	Double precision floating point type	8
cli_asciiz	Zero terminated string of bytes	1*N
cli_pasciiz	Pointer to zero terminated string	1*N
cli_array_of_oid	Array of references	4*N
cli_array_of_bool	Array of booleans	1*N
cli_array_of_int1	Array of tiny integers	1*N
cli_array_of_int2	Array of small integers	2*N
cli_array_of_int4	Array of integers	4*N
cli_array_of_int8	Array of big integers	8*N
cli_array_of_real4	Array of reals	4*N
cli_array_of_real8	Array of long reals	8*N

int cli_open(char const* server_url, 

             int         max_connect_attempts,

             int         reconnect_timeout_sec);

        与服务器建立连接

        参数

        server_url-0终止的字符串，服务器地址和端口，如"localhost:5101", "195.239.208.240:6100"...

        max_connect_attempts-建立连接的尝试次数

        reconnect_timeout_sec-连接尝试的时间间隔，以秒为单位

        返回值

        >= 0-将由所有其它cli调用使用的连接描述符

        <0-cli_result_code中说明的错误吗

int cli_close(int session);

        关闭会话

        参数

        session-cli_open返回的会话描述符

        返回值

        如cli_result_code所述

int cli_statement(int session, char const* stmt);

        指定要在服务器端执行的SubSQL语句。可以建立参数和列的绑定。

        参数

        session-cli_open返回的会话描述符

        stmt-0终止的SubSQL语句字符串

        返回值

        >= 0-语句描述符

        <0 cli_result_code所述的错误码

 

int cli_parameter(int         statement,

                 char const* param_name, 

                 int         var_type,

                 void*       var_ptr);

        将参数与语句绑定

        参数

        statement- cli_statement返回的描述符

        param_name-0终止的参数名字符串。参数名必须以'%'开始

        var_type- cli_var_type中所述的参数类型。只支持标量和0终止字符串类型

        var_ptr-指向变量的指针。

        返回值

        cli_result_code所述的结果编码