华为云用户手册

基于ecpg开发 ecpg(embedded SQL C preprocessor for GaussDB Kernel）是一种用于C语言程序的嵌入式SQL预处理器。一个嵌入式SQL程序由一种普通编程语言编写的代码（此处为C语言）和SQL命令共同组成。要构建该程序，源代码（*.pgc）首先通过嵌入式SQL预处理器，将源代码转换成一个普通C语言程序（*.c），然后再通过编译器处理。转换过的ecpg应用通过嵌入式SQL库（ecpglib）调用libpq库中的函数，与GaussDB Kernel服务器使用普通的前端/后端协议通信。 嵌入式SQL程序是插入了数据库相关动作的特殊代码的C语言程序。这种特殊代码形式通常如下： EXEC SQL ...; 这些语句在语法上取代了一个C语句，可以出现在全局或者是一个函数中。嵌入式SQL语句遵循普通SQL代码的大小写敏感规则，也允许嵌套的C语言代码风格注释（SQL标准的一部分）。不过，程序的C语言部分遵循C语言程序的标准，不支持嵌套注释。 开发流程 ecpg组件介绍 ecpg预处理以及编译执行 管理数据库连接 执行SQL命令 查询结果集 关闭数据库连接 宿主变量 执行动态SQL语句 错误处理 预处理指令 使用库函数 SQL描述符区域 常用示例 ecpg接口参考 父主题： 应用程序开发教程

sqlca 嵌入式SQL接口提供了sqlca（SQL通信区）的全局变量。sqlca包含告警和错误信息。如果在语句执行期间发生多个告警和错误，那么sqlca将只保存最后一个信息。在一个多线程的程序中，每一个线程会自动得到它的sqlca副本。 数据结构如下： struct { char sqlcaid[8]; long sqlabc; long sqlcode; struct { int sqlerrml; char sqlerrmc[SQLERRMC_LEN]; } sqlerrm; char sqlerrp[8]; long sqlerrd[6]; char sqlwarn[8]; char sqlstate[5]; } sqlca; 如果SQL语句没有发生错误，则sqlca.sqlcode为0，sqlca.sqlstate为"00000"。如果发生了告警或者错误，那么sqlca.sqlcode是负数并且sqlca.sqlstate不同于"00000"。SQLSTATE与SQLCODE的具体值可参考SQLSTATE与SQLCODE章节。 如果SQL语句正确执行，那么sqlca.sqlerrd[1]包含被处理行的OID，并且sqlca.sqlerrd[2]包含被处理或返回的行数。 在发生错误或告警时，sqlca.sqlerrm.sqlerrmc将包含描述该错误的字符串。sqlca.sqlerrm.sqlerrml包含存储在sqlca.sqlerrm.sqlerrmc中错误消息的长度（strlen()的结果）。注意：一些消息可能无法适应定长的sqlerrmc数组，它们将被截断。 在发生告警时，sqlca.sqlwarn[2]被设置为W。 sqlcaid、sqlabc、sqlerrp、sqlwarn以及sqlerrd的剩余元素目前未包含有用的信息。 示例如下： /* 整合WHENEVER和sqlca实现错误处理 */EXEC SQL WHENEVER SQLERROR SQLCALL print_sqlca(); void print_sqlca() { fprintf(stderr, "==== sqlca ====\n"); fprintf(stderr, "sqlcode: %ld\n", sqlca.sqlcode); fprintf(stderr, "sqlerrm.sqlerrml: %d\n", sqlca.sqlerrm.sqlerrml); fprintf(stderr, "sqlerrm.sqlerrmc: %s\n", sqlca.sqlerrm.sqlerrmc); fprintf(stderr, "sqlerrd: %ld %ld %ld %ld %ld %ld\n", sqlca.sqlerrd[0],sqlca.sqlerrd[1],sqlca.sqlerrd[2], sqlca.sqlerrd[3],sqlca.sqlerrd[4],sqlca.sqlerrd[5]); fprintf(stderr, "sqlwarn: %d %d %d %d %d %d %d %d\n", sqlca.sqlwarn[0], sqlca.sqlwarn[1], sqlca.sqlwarn[2], sqlca.sqlwarn[3], sqlca.sqlwarn[4], sqlca.sqlwarn[5], sqlca.sqlwarn[6], sqlca.sqlwarn[7]); fprintf(stderr, "sqlstate: %5s\n", sqlca.sqlstate); fprintf(stderr, "===============\n"); } 输出结果形如（此处的错误是一个拼写表名错误）： ==== sqlca ==== sqlcode: -400 sqlerrm.sqlerrml: 49 sqlerrm.sqlerrmc: relation "pg_databasep" does not exist on line 38 sqlerrd: 0 0 0 0 0 0 sqlwarn: 0 0 0 0 0 0 0 0 sqlstate: 42P01 =============== 父主题： 错误处理

环境类 Go环境配置 用户需要在环境变量中配置以下参数： GO111MODULE：用户使用在线导入的方式安装Go驱动时需要设置GO111MODULE为on；如果不希望进行go mod工程的改造，需将GO111MODULE设置为off，并手动下载依赖包，依赖包与驱动根目录和业务代码保持同级。 GOPROXY：用户使用在线导入时需配置包含Go驱动包的路径。 用户可以根据自己场景参数配置Go其他相关环境变量。 通过go env查看Go环境变量配置结果，并且查看Go版本是否在1.13或以上。 go驱动安装 通过在线导入方式安装，目前Go驱动已上传至https://cmc.centralrepo.rnd.huawei.com/go/，用户可以通过配置GOPROXY获取Go驱动代码。配置好环境变量（参考•Go环境配置）后，直接执行go mod tidy更新并下载Go驱动代码包及相关依赖。 下载Go驱动包到本地，进入Go驱动代码根路径，执行go mod tidy下载相关依赖。需要配置GOPATH=${Go所在目录}，go.mod里面需要添加一行“通过replace将Go驱动包替换为本地Go驱动包地址”，表示代码里面所有的import Go驱动包都是走本地路径， 同时依赖也不会从代理里下载。 通过go mod tidy下载相关依赖时可能会下载为某个依赖的低版本，如果依赖的低版本存在漏洞，可以通过更改go.mod文件中对应依赖的版本号，更新依赖到漏洞修复后的版本来规避风险。

命名SQL描述符区域 一个命名SQL描述符区域由一个头部以及一个或多个条目描述符区域构成。头部包含与整个描述区域相关的信息，而条目描述符区域则描述结果行中的某一列。 在使用SQL描述符区域之前，需要分配一个SQL描述符区域： EXEC SQL ALLOCATE DESCRIPTOR identifier; 当不再需要这个描述符区域时，应及时释放： EXEC SQL DEALLOCATE DESCRIPTOR identifier; 要使用一个描述符区域，需要使用INTO子句声明： EXEC SQL FETCH NEXT FROM mycursor INTO SQL DESCRIPTOR mydesc; 如果结果集为空，该描述符区域仍会包含查询的元数据。 对于还没有执行的预备查询，可以使用DESCRIBE得到其结果集的元数据。 EXEC SQL BEGIN DECLARE SECTION; char *sql_stmt = "SELECT * FROM table1"; EXEC SQL END DECLARE SECTION; EXEC SQL PREPARE stmt1 FROM :sql_stmt; EXEC SQL DESCRIBE stmt1 INTO SQL DESCRIPTOR mydesc; 在DESCRIBE和FETCH语句中，INTO和USING关键词的使用相似：它们产生结果集以及一个描述符区域的元数据。 从头部检索一个描述符区域的值并且将其存储到一个宿主变量中： EXEC SQL GET DESCRIPTOR name :hostvar = field; 当前只定义了一个头部描述符区域COUNT，它存放描述符区域的条目（即结果集中包含多少列），宿主变量为一个整数类型，需从条目描述符区域中得到一个具体值： EXEC SQL GET DESCRIPTOR name VALUE num :hostvar = field; num可以是一个字符整数或者一个包含整数的宿主变量。可能的类型如下： CARDINALITY（整数）：结果集中的行数 DATA：实际的数据项（这个范围的实际数据类型取决于查询） DATETIME_INTERVAL_CODE（整数）：当TYPE是9时，DATETIME_INTERVAL_CODE将具有以下值之一：1表示DATE，2表示TIME，3表示TIMESTAMP，4表示TIME WITH TIME ZONE，5表示TIMESTAMP WITH TIME ZONE。 INDICATOR（整数）：指示符（表示一个空值或者一个值截断） LENGTH（整数）：以字符计的数据长度 NAME(string)：列名 OCTET_LENGTH（整数）：以字节计的数据字符表达的长度 PRECISION（整数）：精度（用于类型numeric） RETURNED_LENGTH（整数）：以字符计的数据长度 RETURNED_OCTET_LENGTH（整数）：以字节计的数据字符表达的长度 SCALE（整数）：比例（用于类型numeric） TYPE（整数）：列的数据类型的数字编码 要检索字段数值并且把它存储到一个宿主变量里，使用下面的命令： EXEC SQL GET DESCRIPTOR mydesc VALUE num :hostvar = field num可以是一个字符整数或者一个包含整数的宿主变量。可能的字段有: DATA 实际数据项（因此，这个字段的数据类型依赖于这个查询） NAME(string) 字段名称 手动建立一个描述符区域为一个查询或游标提供输入参数，使用如下命令： EXEC SQL SET DESCRIPTOR name VALUE numfield = :hostvar; 在一个FETCH语句中检索多行记录且用数组类型的宿主变量来存储数据，示例如下： EXEC SQL BEGIN DECLARE SECTION; int id[5]; EXEC SQL END DECLARE SECTION; EXEC SQL FETCH 5 FROM mycursor INTO SQL DESCRIPTOR mydesc; EXEC SQL GET DESCRIPTOR mydesc VALUE 1 :id = DATA; 父主题： SQL描述符区域

SQLSTATE与SQLCODE SQLSTATE是一个由五个字符组成的数组。这五个字符包含数字或大写字母，它表示多种错误或告警情况的代码。SQLSTATE具有一种层次模式：前两个字符表示情况的总体分类，后三个字符表示总体情况的子类。例如：代码00000表示成功状态。 SQLCODE是一个简单的整数形式。值为0表示成功，一个正值表示带附加信息的成功，一个负值表示错误。SQL标准只定义了正值+100，它表示上一个命令返回或者影响了零行，且没有特定的负值。 表1 SQLSTATE与SQLCODE对应关系表 SQLCODE值 SQLSTATE值 含义 0 (ECPG_NO_ERROR) SQLSTATE 00000 表示没有错误。 100 (ECPG_NOT_FOUND) SQLSTATE 02000 一种无害情况，它表示上一个命令检索或者处理了零行，或者已到达游标的末尾。 在循环中处理游标时，可以使用这个代码来检测何时中止该循环，示例如下： while (1) { EXEC SQL FETCH ... ; if (sqlca.sqlcode == ECPG_NOT_FOUND) break; } 实际上WHENEVER NOT FOUND DO BREAK也会在内部这样做，所以一般不会直接使用这种方法。 -12 (ECPG_OUT_OF_MEMORY) SQLSTATE YE001 虚拟内存已被耗尽，数字值被定义为-ENOMEM。 -200 (ECPG_UNSUPPORTED) SQLSTATE YE000 预处理器产生了一些该库无法识别的内容。 -201 (ECPG_TOO_MANY_ARGUMENTS) SQLSTATE 07001 或 07002 表示命令指定的宿主变量数量超过该命令预期。 -202 (ECPG_TOO_FEW_ARGUMENTS) SQLSTATE 07001 或 07002 表示命令指定的宿主变量数量低于该命令的预期。 -203 (ECPG_TOO_MANY_MATCHES) SQLSTATE 21000 表示一个查询已经返回了多个行，但是该语句只准备存储一个结果行。 -204 (ECPG_INT_FORMAT) SQLSTATE 42804 宿主变量是类型int而数据库中的数据是一种不同的类型并且含有不能被解释为int的值。该库使用strtol()进行这种转换。 -205 (ECPG_UINT_FORMAT) SQLSTATE 42804 宿主变量是类型unsigned int而数据库中的数据是一种不同的类型并且含有不能被解释为unsigned int的值。该库使用strtoul()进行这种转换。 -206 (ECPG_FLOAT_FORMAT) SQLSTATE 42804 宿主变量是类型float而数据库中的数据是另一种类型并且含有不能被解释为float的值。该库使用strtod()进行这种转换。 -207 (ECPG_NUMERIC_FORMAT) SQLSTATE 42804 宿主变量是类型numeric而数据库中的数据是另一种类型并且含有不能被解释为numeric的值。 -208 (ECPG_INTERVAL_FORMAT) SQLSTATE 42804 宿主变量是类型interval而数据库中的数据是另一种类型并且含有一个不能被解释为interval的值。 -209 (ECPG_DATE_FORMAT) SQLSTATE 42804 宿主变量是类型date而数据库中的数据是另一种类型并且含有不能被解释为date的值。 -210 (ECPG_TIMESTAMP_FORMAT) SQLSTATE 42804 宿主变量是类型timestamp而数据库中的数据是另一种类型并且含有不能被解释为timestamp的值。 -211 (ECPG_CONVERT_BOOL) SQLSTATE 42804 宿主变量是类型bool而数据库中的数据既不是't'也不是'f'。 -212 (ECPG_EMPTY) SQLSTATE YE000 发送给SQL服务器的语句是空的（通常在一个嵌入式SQL程序中不会发生，因此它可能指向一个内部错误）。 -213 (ECPG_MISSING_INDICATOR) SQLSTATE 22002 返回了一个空值并且没有提供空值指示符。 -214 (ECPG_NO_ARRAY) SQLSTATE 42804 在要求一个数组的地方使用了一个普通变量。 -215 (ECPG_DATA_NOT_ARRAY) SQLSTATE 42804 在一个要求数组值的地方数据库返回了一个普通变量。 -220 (ECPG_NO_CONN) SQLSTATE 08003 程序尝试访问一个不存在的连接。 -221 (ECPG_NOT_CONN) SQLSTATE YE000 程序尝试访问一个存在的连接但是它没有打开（这是一个内部错误）。 -230 (ECPG_INVALID_STMT) SQLSTATE 26000 尝试使用的语句还没有被准备好。 -239 (ECPG_INFORMIX_DUPLICATE_KEY) SQLSTATE 23505 重复键错误，违背唯一约束。 -240 (ECPG_UNKNOWN_DESCRIPTOR) SQLSTATE 33000 没有找到指定的描述符，尝试使用的语句还没有被准备好。 -241 (ECPG_INVALID_DESCRIPTOR_INDEX) SQLSTATE 07009 指定的描述符超出范围。 -242 (ECPG_UNKNOWN_DESCRIPTOR_ITEM) SQLSTATE YE000 请求了一个非法的描述符（这是一个内部错误）。 -243 (ECPG_VAR_NOT_NUMERIC) SQLSTATE 07006 在执行一个动态语句期间，数据库返回了一个numeric值而宿主变量不是numeric类型的。 -244 (ECPG_VAR_NOT_CHAR) SQLSTATE 07006 在执行一个动态语句期间，数据库返回了一个非numeric值而宿主变量是numeric类型的。 -284 (ECPG_INFORMIX_SUBSELECT_NOT_ONE) SQLSTATE 21000 子查询的结果不是单一行。 -400 (ECPG_PGSQL) - SQL服务器导致了某个错误。该消息包含来自SQL服务器的错误消息。 -401 (ECPG_TRANS) SQLSTATE 08007 SQL服务器通知我们不能启动、提交或回滚事务。 -402 (ECPG_CONNECT) SQLSTATE 08001 无法建立数据库连接。 -403 (ECPG_DUPLICATE_KEY) SQLSTATE 23505 重复键错误，违背唯一约束。 -404 (ECPG_SUBSELECT_NOT_ONE) SQLSTATE 21000 子查询的结果不是单一行。 -602 (ECPG_WARNING_UNKNOWN_PORTAL) SQLSTATE 34000 指定了一个非法的游标名。 -603 (ECPG_WARNING_IN_TRANSACTION) SQLSTATE 25001 事务正在进行。 -604 (ECPG_WARNING_NO_TRANSACTION) SQLSTATE 25P01 没有活动（正在进行）的事务。 -605 (ECPG_WARNING_PORTAL_EXISTS) SQLSTATE 42P03 指定了一个现有的游标名。 ecpg为嵌入式SQL新增加的SQLSTATE码有：22002，07001，07002，07006，07009，33000，42601，42804，42P03，YE000，YE001。其余SQLSTATE码沿用内核SQLSTATE码。 SQLSCODE为-400表示ecpg检测到内核服务器返回错误，其SQLSTATE为内核相应错误的SQLSTATE。 父主题： 错误处理

ifdef，ifndef，else，elif和endif指令 ecpg提供了ifdef、ifndef、else、elif和endif条件编译指令。在预处理时，按照不同的条件去编译程序的不同部分，使用时，需要添加EXEC SQL前缀关键字。 示例如下： EXEC SQL ifndef TZVAR; EXEC SQL SET TIMEZONE TO 'GMT'; EXEC SQL elif TZNAME; EXEC SQL SET TIMEZONE TO TZNAME; EXEC SQL else; EXEC SQL SET TIMEZONE TO TZVAR; EXEC SQL endif; 父主题： 预处理指令

define和undef指令 嵌入式SQL具有类似于C语言中#define指令： EXEC SQL DEFINE name;EXEC SQL DEFINE name value;EXEC SQL UNDEF name; 示例如下： /* 定义名称 */EXEC SQL DEFINE HAVE_FEATURE;/* 定义常量 */EXEC SQL DEFINE MYNUMBER 12;EXEC SQL DEFINE MYSTRING 'abc';/* 使用 UNDEF 移除定义 */EXEC SQL UNDEF MYNUMBER; 在嵌入式SQL程序中也可以使用C语言版本的#define和#undef。区别在于定义的值会在哪里被计算，如果使用EXEC SQL DEFINE，那么ecpg预处理阶段会计算这些定义并替换值。如下示例，ecpg对其进行替换并且编译器不会解析名为MYNUMBER的任何名称或标识符： EXEC SQL DEFINE MYNUMBER 12; ... EXEC SQL UPDATE Tbl SET col = MYNUMBER; 不能把#define用于一个将要在一个嵌入式SQL查询中使用的变量，因为在这种情况下嵌入式SQL预编译器不能看到这个声明。 父主题： 预处理指令

设置回调 设置回调操作，当告警或者错误发生时，直接执行具体操作进行处理，设置回调命令如下： EXEC SQL WHENEVER condition action; condition取值范围： SQLERROR：当在SQL语句执行期间发生错误时，调用指定操作。 SQLWARNING：当在SQL语句执行期间发生告警时，调用指定操作。 NOT FOUND：当SQL语句检索或者影响零行，则调用指定操作。 action取值范围： CONTINUE：忽略回调错误条件，继续执行，通常可以用来停止break包含条件，为缺省值。 GOTO label/GO TO label：跳转到指定标签（使用C语言goto语句）。 SQLPRINT：输出消息到标准错误。 STOP：调用exit(1)，终止程序。 DO BREAK：执行C语句break，只有在循环中或者switch语句中使用。 SQLCALL name (args) / DO name (args)：调用具有指定参数的指定C语言函数。 示例如下： /* 当出现一个告警时它打印一个消息，发生一个错误时中止程序。 */EXEC SQL WHENEVER SQLWARNING SQLPRINT; EXEC SQL WHENEVER SQLERROR STOP; 语句EXEC SQL WHENEVER是SQL预处理器的一个指令，而非一个C语言语句。不管C语言程序的流程如何，该语句设置的错误或告警动作都适用于位于处理程序设置点之后的嵌入式SQL语句，除非第一个EXEC SQL WHENEVER语句和导致错误或告警情况发生的SQL语句之间为同一个情况设置了不同的动作。因此下面的两个C语言程序都不会得到预期的效果： /* * 错误 */ int main(int argc, char *argv[]) { ... if (verbose) { EXEC SQL WHENEVER SQLWARNING SQLPRINT; } ... EXEC SQL SELECT ...; ... } /* * 错误 */ int main(int argc, char *argv[]) { ... set_error_handler(); ... EXEC SQL SELECT ...; ... } static void set_error_handler(void) { EXEC SQL WHENEVER SQLERROR STOP; } 当使用DO BREAK时只能用于while/for/switch场景，且用完需要使用CONTINUE语句忽略。 父主题： 错误处理

执行具有输入参数的语句 准备一个普通语句，通过替换参数（在想要替换参数的地方写上问号）执行它的特定版本。使用EXECUTE语句通过USING子句给定参数执行准备语句。示例如下： EXEC SQL BEGIN DECLARE SECTION; const char *stmt = "INSERT INTO test1 VALUES(?, ?);";EXEC SQL END DECLARE SECTION; /* PREPARE 准备一个语句用于执行 */ EXEC SQL PREPARE mystmt FROM :stmt; ... /* 单引号为有效字符，若用字符串需用双引号 */ EXEC SQL EXECUTE mystmt USING 42, 'foobar'; /* 当你不再需要预备语句时，你应该释放它 */ EXEC SQL DEALLOCATE PREPARE name; 父主题： 执行动态SQL语句

执行没有结果集的语句 执行EXECUTE IMMEDIATE命令示例如下： EXEC SQL BEGIN DECLARE SECTION; const char *stmt = "CREATE TABLE test1 (...);";EXEC SQL END DECLARE SECTION; EXEC SQL EXECUTE IMMEDIATE :stmt; EXECUTE IMMEDIATE可以用于不返回结果集的SQL语句，比如：DDL，INSERT，UPDATE，DELETE语句。但不能用这种方式执行检索数据的语句，比如：SELECT语句。 父主题： 执行动态SQL语句

类型映射 当ecpg应用程序在GaussDB Kernel服务器和C语言程序之间交换值时（例如：从服务器检索查询结果或者执行带有输入参数的SQL语句），在GaussDB Kernel数据类型和宿主语言变量类型（具体的C语言数据类型）之间需要进行值的转换。有两种数据类型可以使用：一些简单的GaussDB Kernel数据类型，如integer和text，可以直接被应用程序读取和写入；其他GaussDB Kernel数据类型，如timestamp和numeric，只能通过特殊库函数进行访问，参见ecpg接口参考章节。 表1 GaussDB Kernel数据类型和C变量类型之间的映射 GaussDB Kernel数据类型 宿主变量数据类型 smallint short integer int bigint long long int boolean bool character(n), varchar(n), text char[n+1], VARCHAR[n+1] double precision double real float smallserial short serial int bigserial long long int oid unsigned int name char[NAMEDATALEN] date date [a] timestamp timestamp [a] interval interval [a] decimal decimal [a] numeric numeric [a] [a]这种类型可以通过访问特殊数据类型访问。 当前仅支持对于C语言的基本数据类型的使用或者组合，不支持C++语言中string数据类型用作宿主变量数据类型。 当前ecpg仅对GaussDB Kernel SQL的常用数据类型做映射，具体支持项可参考表1。 父主题： 宿主变量

处理字符串 处理SQL字符串数据类型（例如：varchar、text），有两种方式来声明宿主变量： 方式一：使用char[]（一个char字符串），C语言程序中处理字符数据最常见的方式。 EXEC SQL BEGIN DECLARE SECTION; char str[50];EXEC SQL END DECLARE SECTION; 注意字符串必须控制长度，如果上述示例的宿主变量用作存放查询结果且查询命令返回的字符串长度超过49字节，那么将会发生缓冲区溢出。 方式二：使用VARCHAR类型，ecpg提供的一种特殊类型。在一个VARCHAR类型数组上的定义会被转变成一个struct类型。如下声明： VARCHAR var[180]; 会被转变成： struct varchar_var { int len; char arr[180]; } var; 要在一个VARCHAR宿主变量中存储一个字符串，该宿主变量必须被声明为包含零字节为终止符长度的字符串。字段arr存放以零字节为终止符的字符串，字段len保存存储在arr中的字符串的长度，计算长度时不包括终止符。当宿主变量被用于一个查询的输入时，如果strlen(arr)和len结果不同，将使用较短的那一个。 VARCHAR可以被写成大写或小写形式，但是不能大小写混合。 char和VARCHAR类型宿主变量也可以保存其他SQL类型的值，它们将被存储为字符串形式。 父主题： 宿主变量

声明段 要实现嵌入式SQL-C程序和数据库间的数据交互（例如：从SQL-C程序把查询语句中的参数传递给数据库，或者从数据库向嵌入式SQL-C程序传回数据），需要在特殊的标记段里面声明包含此数据的C语言变量，以便预处理器能够识别。 标记段以下面的代码开始： EXEC SQL BEGIN DECLARE SECTION; 以下面的代码结束： EXEC SQL END DECLARE SECTION; 在此之间，必须有常规的C语言变量声明，比如： int x = 4;char foo[16], bar[16]; 标记段代码开始和结束之间声明的宿主变量类型必须为当前支持的数据类型，详见表1。 可以隐式地创建一个声明段声明变量：EXEC SQL int i = 4。 那些不在SQL命令里使用的变量可以在这些特殊的声明段外面声明。 结构体或者联合体的定义也必须在DECLARE段中列出。否则预处理器就无法处理这些类型，因为它不知道定义。 父主题： 宿主变量

概述 在嵌入式SQL中进行C语言程序和SQL语句之间的数据传递不需要把数据粘贴到语句中，只需要在SQL语句里写上C语言变量的名称，前缀加一个冒号即可。示例如下： EXEC SQL INSERT INTO sometable VALUES (:v1, 'foo', :v2); 这个语句引用了两个C语言变量：v1和v2，并且使用一个普通的SQL字串文本，这表明一条SQL语句内并不限制只使用某一种数据。 父主题： 宿主变量

宿主变量 本节详细介绍如何在C语言程序和嵌入式SQL程序之间使用宿主变量传递数据。在嵌入式SQL-C程序中，我们将C语言作为宿主语言，将EXEC SQL [Command]语句认为是宿主语言的嵌入式SQL，因此将C语言程序中用于嵌入式SQL语句的变量称为宿主变量。 概述 声明段 检索查询 类型映射 处理字符串 使用非初级类型的宿主变量 访问特殊数据类型 处理非初级SQL数据类型 父主题： 基于ecpg开发

检索查询 对于常用的检索查询，嵌入式SQL提供了常规命令SELECT和FETCH的特殊变体。这些命令使用特殊的INTO子句，用以指定检索出来的数值存储在哪些宿主变量里。SELECT用于返回单行的查询，FETCH用于使用游标返回多行的查询。 使用SELECT /* * 假定有这个表： * CREATE TABLE test1 (a int, b varchar(50)); */EXEC SQL BEGIN DECLARE SECTION; int v1; VARCHAR v2;EXEC SQL END DECLARE SECTION; ... EXEC SQL SELECT a, b INTO :v1, :v2 FROM test; INTO子句出现在选择列表和FROM子句之间。选择列表和INTO后面的列表的元素（也叫目标列表）个数必须相同。 使用FETCH EXEC SQL BEGIN DECLARE SECTION; int v1; VARCHAR v2;EXEC SQL END DECLARE SECTION; ... EXEC SQL DECLARE foo CURSOR FOR SELECT a, b FROM test; ... do { ... EXEC SQL FETCH NEXT FROM foo INTO :v1, :v2; ... } while (...); 这里的INTO子句出现在所有SQL子句后面。 父主题： 宿主变量

查询结果集 返回单行结果的SELECT语句可以直接使用EXEC SQL执行，可参考执行SQL命令章节。 示例： /* 首先建立一个表并插入数据 */EXEC SQL CREATE TABLE test_table (number1 integer, number2 integer);EXEC SQL INSERT INTO test_table (number1, number2) VALUES (2, 1);/* 查询结果为单行,:num 为宿主变量 */EXEC SQL SELECT number1 INTO :num FROM test_table WHERE number2 = 1; 若要处理多行结果集，则必须使用游标，可参考使用游标章节（特殊情况下，应用程序可以一次取出多行结果写入到数组类型的宿主变量中，可参考使用非初级类型的宿主变量章节）。 示例： /* 首先建立一个表并插入数据 */ EXEC SQL CREATE TABLE test_table (number1 integer, number2 integer); EXEC SQL INSERT INTO test_table (number1, number2) VALUES (2, 1); EXEC SQL INSERT INTO test_table (number1, number2) VALUES (3, 1); EXEC SQL INSERT INTO test_table (number1, number2) VALUES (4，1); EXEC SQL INSERT INTO test_table (number1, number2) VALUES (5, 1);/* 定义宿主变量 */EXEC SQL BEGIN DECLARE SECTION; int v1; int v2;EXEC SQL END DECLARE SECTION; /* 声明游标 */ EXEC SQL DECLARE test_bar CURSOR FOR SELECT number1, number2 FROM test_table ORDER BY number1; /* 打开游标 */ EXEC SQL OPEN test_bar; /* 当游标到达结果集末尾时跳出循环 */ EXEC SQL WHENEVER NOT FOUND DO BREAK; /* 获取查询结果集 */ while(1) { EXEC SQL FETCH NEXT FROM test_bar INTO :v1, :v2; printf("number1 = %d, number2 = %d\n",v1,v2); } /* 关闭游标 */ EXEC SQL CLOSE test_bar; 父主题： 基于ecpg开发

示例 EXEC SQL SET DESCRIPTOR indesc COUNT = 1; EXEC SQL SET DESCRIPTOR indesc VALUE 1 DATA = 2; EXEC SQL SET DESCRIPTOR indesc VALUE 1 DATA = :val1; EXEC SQL SET DESCRIPTOR indesc VALUE 2 INDICATOR = :val1, DATA = 'some string'; EXEC SQL SET DESCRIPTOR indesc VALUE 2 INDICATOR = :val2null, DATA = :val2;

示例 EXEC SQL TYPE customer IS struct { varchar name[50]; int phone; };EXEC SQL TYPE cust_ind IS struct ind { short name_ind; short phone_ind; };EXEC SQL TYPE c IS char reference;EXEC SQL TYPE ind IS union { int integer; short smallint; };EXEC SQL TYPE intarray IS int[AMOUNT];EXEC SQL TYPE str IS varchar[BUFFERSIZ];EXEC SQL TYPE string IS char[11]; 使用EXEC SQL TYPE的示例： EXEC SQL WHENEVER SQLERROR SQLPRINT; EXEC SQL TYPE tt IS struct { varchar v[256]; int i; }; EXEC SQL TYPE tt_ind IS struct ind { short v_ind; short i_ind; }; int main(void) { EXEC SQL BEGIN DECLARE SECTION; tt t; tt_ind t_ind; EXEC SQL END DECLARE SECTION; EXEC SQL CONNECT TO testdb AS con1; EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT; EXEC SQL SELECT current_database(), 256 INTO :t:t_ind LIMIT 1; printf("t.v = %s\n", t.v.arr); printf("t.i = %d\n", t.i); printf("t_ind.v_ind = %d\n", t_ind.v_ind); printf("t_ind.i_ind = %d\n", t_ind.i_ind); EXEC SQL DISCONNECT con1; return 0; } 该示例输出为： t.v = testdb t.i = 256 t_ind.v_ind = 0 t_ind.i_ind = 0

示例 EXEC SQL WHENEVER NOT FOUND CONTINUE; EXEC SQL WHENEVER NOT FOUND DO BREAK; EXEC SQL WHENEVER SQLWARNING SQLPRINT; EXEC SQL WHENEVER SQLWARNING DO warn(); EXEC SQL WHENEVER SQLERROR sqlprint; EXEC SQL WHENEVER SQLERROR SQLCALL print2(); EXEC SQL WHENEVER SQLERROR DO handle_error("select"); EXEC SQL WHENEVER SQLERROR DO sqlnotice(NULL, NONO);EXEC SQL WHENEVER SQLERROR DO sqlprint(); EXEC SQL WHENEVER SQLERROR GOTO error_label; EXEC SQL WHENEVER SQLERROR STOP; 使用WHENEVER NOT FOUND BREAK来处理结果集的循环： int main(void) { EXEC SQL CONNECT TO testdb AS con1; EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT; EXEC SQL ALLOCATE DESCRIPTOR d; EXEC SQL DECLARE cur CURSOR FOR SELECT current_database(), 'hoge', 256; EXEC SQL OPEN cur; /* 当到达结果集末尾时，跳出循环 */ EXEC SQL WHENEVER NOT FOUND DO BREAK; while (1) { EXEC SQL FETCH NEXT FROM cur INTO SQL DESCRIPTOR d; ... } EXEC SQL CLOSE cur; EXEC SQL COMMIT; EXEC SQL DEALLOCATE DESCRIPTOR d; EXEC SQL DISCONNECT ALL; return 0; }

示例 int main(void) { EXEC SQL CONNECT TO testdb AS DEFAULT USER testuser; EXEC SQL CONNECT TO testdb AS con1 USER testuser; EXEC SQL CONNECT TO testdb AS con2 USER testuser; EXEC SQL CONNECT TO testdb AS con3 USER testuser; EXEC SQL DISCONNECT CURRENT; /* 关闭 con3 */ EXEC SQL DISCONNECT DEFAULT; /* 关闭 DEFAULT */ EXEC SQL DISCONNECT ALL; /* 关闭 con2 以及 con1 */ return 0; }

示例 EXEC SQL ALLOCATE DESCRIPTOR mydesc;EXEC SQL PREPARE stmt1 FROM :sql_stmt;EXEC SQL DESCRIBE stmt1 INTO SQL DESCRIPTOR mydesc;EXEC SQL GET DESCRIPTOR mydesc VALUE 1 :charvar = NAME;EXEC SQL DEALLOCATE DESCRIPTOR mydesc;

示例 char *stmt = "SELECT * FROM test1 WHERE a = ? AND b = ?";EXEC SQL ALLOCATE DESCRIPTOR outdesc;EXEC SQL PREPARE foo FROM :stmt;EXEC SQL EXECUTE foo USING SQL DESCRIPTOR indesc INTO SQL DESCRIPTOR outdesc;

示例 检索结果集中列数： EXEC SQL GET DESCRIPTOR d :d_count = COUNT; 在第一列中检索数据长度： EXEC SQL GET DESCRIPTOR d VALUE 1 :d_returned_octet_length = RETURNED_OCTET_LENGTH; 检索作为字符串第二列的数据主体： EXEC SQL GET DESCRIPTOR d VALUE 2 :d_data = DATA; 执行SELECT current_database();并且显示列数、列数据长度和列数据的完整过程示例： int main(void) { EXEC SQL BEGIN DECLARE SECTION; int d_count; char d_data[1024]; int d_returned_octet_length; EXEC SQL END DECLARE SECTION; EXEC SQL CONNECT TO testdb AS con1 USER testuser; EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT; EXEC SQL ALLOCATE DESCRIPTOR d; /* 描述、打开一个游标，并且分配一个描述符给该游标 */ EXEC SQL DECLARE cur CURSOR FOR SELECT current_database(); EXEC SQL OPEN cur; EXEC SQL FETCH NEXT FROM cur INTO SQL DESCRIPTOR d; /* 得到全部列的数量 */ EXEC SQL GET DESCRIPTOR d :d_count = COUNT; printf("d_count = %d\n", d_count); /* 得到一个返回列的长度 */ EXEC SQL GET DESCRIPTOR d VALUE 1 :d_returned_octet_length = RETURNED_OCTET_LENGTH; printf("d_returned_octet_length = %d\n", d_returned_octet_length); /* 将返回的列取出成一个字符串 */ EXEC SQL GET DESCRIPTOR d VALUE 1 :d_data = DATA; printf("d_data = %s\n", d_data); /* 关闭 */ EXEC SQL CLOSE cur; EXEC SQL COMMIT; EXEC SQL DEALLOCATE DESCRIPTOR d; EXEC SQL DISCONNECT ALL; return 0; } 该示例执行结果为： d_count = 1 d_returned_octet_length = 6 d_data = testdb

参数说明 connection_target 以下列形式之一指定连接的目标服务器： [ database_name ] [ @host ] [ :port ]：通过TCP/IP连接。 unix:postgresql://host [ :port ] / [ database_name ] [ ?connection_option ]：通过Unix域套接字连接。 tcp:postgresql://host [ :port ] / [ database_name ] [ ?connection_option ]：通过TCP/IP连接。 SQL string constant：包含上述形式之一的值。 connection_name 用于该连接的一个可选标识符，可以在其他命令中引用它。可以是一个SQL标识符或者一个宿主变量。 connection_user 用于数据库连接的用户名。 使用user_name/password、user_name SQLIDENTIFIED BY password或者user_name USING password之一，这个参数也能指定用户名和口令。 用户名和口令可以是SQL标识符、字符串常量或者宿主变量。 上述参数中斜体部分为变量，请根据实际情况进行修改。

示例 声明用于查询的游标示例： EXEC SQL DECLARE C CURSOR FOR SELECT * FROM My_Table; EXEC SQL DECLARE C CURSOR FOR SELECT Item1 FROM T; EXEC SQL DECLARE cur1 CURSOR FOR SELECT version(); 声明用于预备语句的游标示例： EXEC SQL PREPARE stmt1 AS SELECT version(); EXEC SQL DECLARE cur1 CURSOR FOR stmt1;

示例 指定连接参数的变体的示例： EXEC SQL CONNECT TO "connectdb" AS main; EXEC SQL CONNECT TO "connectdb" AS second; EXEC SQL CONNECT TO 'connectdb' AS main; EXEC SQL CONNECT TO REGRESSDB1 as main; EXEC SQL CONNECT TO connectdb AS :id; EXEC SQL CONNECT TO connectdb AS main USER connectuser/connectdb; EXEC SQL CONNECT TO connectdb AS main USER connectuser USING "connectdb"; EXEC SQL CONNECT TO connectdb AS main; EXEC SQL CONNECT TO tcp:postgresql://localhost/connectdb USER connectuser IDENTIFIED BY connectpw; EXEC SQL CONNECT TO tcp:postgresql://localhost:20/connectdb USER connectuser SQLIDENTIFIED BY connectpw; EXEC SQL CONNECT TO unix:postgresql://localhost/connectdb USER connectuser SQLIDENTIFIED BY "connectpw"; EXEC SQL CONNECT TO unix:postgresql://localhost/connectdb USER connectuser USING "connectpw"; 使用宿主变量指定连接参数的示例： int main(void) { EXEC SQL BEGIN DECLARE SECTION; char *dbname = "testdb"; /* 数据库名 */ char *user = "testuser"; /* 连接用户名 */ char *pwd = "pwd_123_pwd"; /* 密码 */ char *connection = "tcp:postgresql://localhost:5432/testdb"; /* 连接字符串 */ char ver[256]; /* 存储版本字符串的缓冲区 */ EXEC SQL END DECLARE SECTION; ECPGdebug(1, stderr); EXEC SQL CONNECT TO :dbname; EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT; EXEC SQL SELECT version() INTO :ver; EXEC SQL DISCONNECT; printf("version: %s\n", ver); EXEC SQL CONNECT TO :connection USER :user USING :pwd; EXEC SQL SELECT pg_catalog.set_config('search_path', '', false); EXEC SQL COMMIT; EXEC SQL SELECT version() INTO :ver; EXEC SQL DISCONNECT; printf("version: %s\n", ver); return 0; }

执行sql语句 创建一个表： EXEC SQL CREATE TABLE foo (number integer, ascii char(16));EXEC SQL CREATE UNIQUE INDEX num1 ON foo(number); 插入一行： EXEC SQL INSERT INTO foo (number, ascii) VALUES (9999, 'doodad'); 删除一行： EXEC SQL DELETE FROM foo WHERE number = 9999; 更新表数据： EXEC SQL UPDATE foo SET ascii = 'foobar' WHERE number = 9999; 单行查询数据： EXEC SQL SELECT number INTO :FooBar FROM foo WHERE ascii = 'doodad'; 展示运行时参数： EXEC SQL SHOW search_path INTO :foo; :foo形式的记号是宿主变量，即指向C程序中的变量，可参考宿主变量章节。 父主题： 执行SQL命令

事务管理 在ecpg缺省模式下，语句只有在EXEC SQL COMMIT发出的时候才被提交，嵌入的SQL接口也支持事务的自动提交（通过EXEC SQL SET AUTOCOMMIT TO ON语句设置自动提交）。在自动提交模式下，每条命令都是自动提交的，除非它们包围在一个明确的事务块里。自动提交模式可以用EXEC SQL SET AUTOCOMMIT TO OFF语句关闭。 常见事务管理命令如下： EXEC SQL COMMIT：提交正在进行的事务。 EXEC SQL ROLLBACK：回滚正在进行的事务。 EXEC SQL SET AUTOCOMMIT TO ON：启动自动提交模式。 SET AUTOCOMMIT TO OFF：关闭自动提交模式，缺省模式。 父主题： 执行SQL命令

使用游标 使用游标可以检索出多行的结果集，应用程序必须声明一个游标并且从游标中抓取每一行数据。 声明一个游标： EXEC SQL DECLARE foo_bar CURSOR FOR SELECT number, ascii FROM foo ORDER BY ascii; 打开游标： EXEC SQL OPEN foo_bar; 从游标中抓取一行数据： EXEC SQL FETCH foo_bar INTO :FooBar, DooDad; 关闭游标： EXEC SQL CLOSE foo_bar; 更多游标的使用细节可参考DECLARE，关于FETCH命令的细节可参考FETCH。 父主题： 执行SQL命令