数据库执行语句函数

与数据库服务器的连接成功建立，便可以使用这里描述的函数执行SQL查询和命令。

PQclear

功能描述

释放与PGresult相关联的存储空间，任何不再需要的查询结果都应该用PQclear释放掉。

原型

void PQclear(PGresult *res);

参数

表7-38 PQclear参数

关键字	参数说明
res	包含查询结果的对象指针。

注意事项

PGresult不会自动释放，当提交新的查询时它并不消失，甚至断开连接后也不会。要删除它，必须调用PQclear，否则则会有内存泄漏。

示例

请参见7.3.5示例章节。

PQexec

功能描述

向服务器提交一条命令并等待结果。

原型

PGresult *PQexec(PGconn *conn, const char *command);

参数

表7-39 PQexec参数

关键字	参数说明
conn	指向包含链接的对象指针。
command	需要执行的查询字符串。

返回值

PGresult：包含查询结果的对象指针。

注意事项

应该调用PQresultStatus函数来检查任何错误的返回值（包括空指针的值，在这种情况下它将返回PGRES_FATAL_ERROR）。使用PQerrorMessage获取有关错误的更多信息。

命令字符串可以包括多个SQL命令（用分号分隔）。在一个PQexec调用中发送的多个查询是在一个事务里处理的，除非在查询字符串里有明确的BEGIN/COMMIT命令把整个字符串分隔成多个事务。请注意，返回的PGresult结构只描述字符串里执行的最后一条命令的结果，如果有一个命令失败，那么字符串处理的过程就会停止，并且返回的PGresult会描述错误条件。

示例

请参见7.3.5示例章节。

PQexecParams

功能描述

执行一个绑定参数的命令。

原型

PGresult* PQexecParams(PGconn* conn,  
                       const char* command, 
                       int nParams, 
                       const Oid* paramTypes, 
                       const char* const* paramValues, 
                       const int* paramLengths, 
                       const int* paramFormats,  
                       int resultFormat);

参数

表3-4

关键字	参数说明
conn	连接句柄。
command	SQL文本串。
nParams	绑定参数的个数
paramTypes	绑定参数类型。
paramValues	绑定参数的值。
paramLengths	参数长度。
paramFormats	参数格式（文本或二进制）。
resultFormat	返回结果格式（文本或二进制）。

返回值

PGresult类型指针。

PQexecParamsBatch

功能描述

执行一个批量绑定参数的命令。

原型

PGresult* PQexecParamsBatch(PGconn* conn,  
                            const char* command, 
                            int nParams, 
                            int nBatch,  
                            const Oid* paramTypes, 
                            const char* const* paramValues, 
                            const int* paramLengths, 
                            const int* paramFormats, 
                            int resultFormat);

参数

表3-5

关键字	参数说明
conn	连接句柄。
command	SQL文本串。
nParams	绑定参数的个数
nBatch	批量操作数。
paramTypes	绑定参数类型。
paramValues	绑定参数的值。
paramLengths	参数长度。
paramFormats	参数格式（文本或二进制）。
resultFormat	返回结果格式（文本或二进制）。

返回值

PGresult类型指针。

PQexecPrepared

功能描述

发送一个请求来用给定参数执行一个预备语句，并且等待结果。

原型

PGresult* PQexecPrepared(PGconn* conn,  
                         const char* stmtName,  
                         int nParams,  
                         const char* const* paramValues, 
                         const int* paramLengths, 
                         const int* paramFormats, 
                         int resultFormat);

参数

表3-6

关键字	参数说明
conn	连接句柄。
stmtName	stmt名称，可以用”“或者NULL来引用未命名语句，否则它必须是一个现有预备语句的名字。
nParams	参数个数。
paramValues	参数的实际值。
paramLengths	参数的实际数据长度。
paramFormats	参数的格式（文本或二进制）。
resultFormat	结果的格式（文本或二进制）。

返回值

PGresult类型指针。

PQexecPreparedBatch

功能描述

发送一个请求来用给定的批量参数执行一个预备语句，并且等待结果。

原型

PGresult* PQexecPreparedBatch(PGconn* conn,  
                              const char* stmtName,  
                              int nParams, 
                              int nBatchCount, 
                              const char* const* paramValues, 
                              const int* paramLengths, 
                              const int* paramFormats, 
                              int resultFormat);

参数

表3-7

关键字	参数说明
conn	连接句柄。
stmtName	stmt名称，可以用”“或者NULL来引用未命名语句，否则它必须是一个现有预备语句的名字。
nParams	参数个数。
nBatchCount	批量数。
paramValues	参数的实际值。
paramLengths	参数的实际数据长度。
paramFormats	参数的格式（文本或二进制）。
resultFormat	结果的格式（文本或二进制）。

返回值

PGresult类型指针。

PQfname

功能描述

返回与给定列号相关联的列名。列号从 0开始。调用者不应该直接释放该结果。它将在相关的PGresult句柄被传递给PQclear之后被释放。

原型

char *PQfname(const PGresult *res, 
              int column_number);

参数

表3-8

关键字	参数说明
res	操作结果句柄。
column_number	列数。

返回值

char类型指针。

示例

参见：7.3.5示例

PQgetvalue

功能描述

返回一个PGresult的一行的单一域值。行和列号从 0开始。调用者不应该直接释放该结果。它将在相关的PGresult句柄被传递给PQclear之后被释放。

原型

char *PQgetvalue(const PGresult *res, 
                 int row_number, 
                 int column_number);

参数

表3-9

关键字	参数说明
res	操作结果句柄。
row_number	行数。
column_number	列数。

返回值

对于文本格式的数据，PQgetvalue返回的值是该域值的一种空值结束的字符串表示。

对于二进制格式的数据，该值是由该数据类型的typsend和typreceive函数决定的二进制表示。

如果该域值为空，则返回一个空串。

示例

参见：7.3.5示例

PQnfields

功能描述

返回查询结果中每一行的列（域）数。

原型

int PQnfields(const PGresult *res);

参数

表3-10

关键字	参数说明
res	操作结果句柄。

返回值

int类型数字。

示例

参见：7.3.5示例

PQntuples

功能描述

返回查询结果中的行（元组）数。因为它返回一个整数结果，在 32位操作系统上大型的结果集可能使返回值溢出。

原型

int PQntuples(const PGresult *res);

参数

表3-11

关键字	参数说明
res	操作结果句柄。

返回值

int类型数字

示例

参见：7.3.5示例

PQprepare

功能描述

用给定的参数提交请求，创建一个预备语句，然后等待结束。

原型

PGresult *PQprepare(PGconn *conn, 
                    const char *stmtName, 
                    const char *query, 
                    int nParams, 
                    const Oid *paramTypes);

参数

表7-40 PQprepare参数

关键字	参数说明
conn	指向包含链接的对象指针。
stmtName	需要执行的stmt名称。
query	需要执行的查询字符串。
nParams	参数个数。
paramTypes	声明参数类型的数组。

返回值

PGresult：包含查询结果的对象指针。

注意事项

PQprepare创建一个为PQexecPrepared执行用的预备语句，本特性支持命令的重复执行，不需要每次都进行解析和规划。PQprepare仅在协议3.0及以后的连接中支持，使用协议2.0时，PQprepare将失败。
该函数从查询字符串创建一个名为stmtName的预备语句，该查询字符串必须包含一个SQL命令。stmtName可以是”“来创建一个未命名的语句，在这种情况下，任何预先存在的未命名的语句都将被自动替换；否则，如果在当前会话中已经定义了语句名称，则这是一个错误。如果使用了任何参数，那么在查询中将它们称为$1,$2等。nParams是在paramTypes[]数组中预先指定类型的参数的数量。（当nParams为0时，数组指针可以为NULL）paramTypes[]通过OID指定要分配给参数符号的数据类型。如果paramTypes为NULL，或者数组中的任何特定元素为零，服务器将按照对非类型化字面字符串的相同方式为参数符号分配数据类型。另外，查询可以使用数字高于nParams的参数符号；还将推断这些符号的数据类型。

通过执行SQLPREPARE语句，还可以创建与PQexecPrepared一起使用的预备语句。此外，虽然没有用于删除预备语句的libpq函数，但是SQL DEALLOCATE语句可用于此目的。

示例

请参见7.3.5示例章节。

PQresultStatus

功能描述

返回命令的结果状态。

原型

ExecStatusType PQresultStatus(const PGresult *res);

参数

表7-41 PQresultStatus参数

关键字	参数说明
res	包含查询结果的对象指针。

返回值

PQresultStatus：命令执行结果的枚举，包括：

PQresultStatus可以返回下面数值之一： 
PGRES_EMPTY_QUERY 
发送给服务器的字串是空的。 
 
PGRES_COMMAND_OK 
成功完成一个不返回数据的命令。 
 
PGRES_TUPLES_OK 
成功执行一个返回数据的查询（比如SELECT或者SHOW）。 
 
PGRES_COPY_OUT 
（从服务器）Copy Out （拷贝出）数据传输开始。 
 
PGRES_COPY_IN 
Copy In（拷贝入）（到服务器）数据传输开始。 
 
PGRES_BAD_RESPONSE 
服务器的响应无法理解。 
 
PGRES_NONFATAL_ERROR 
发生了一个非致命错误（通知或者警告）。 
 
PGRES_FATAL_ERROR 
发生了一个致命错误。 
 
PGRES_COPY_BOTH 
拷贝入/出（到和从服务器）数据传输开始。这个特性当前只用于流复制， 所以这个状态不会在普通应用中发生。 
 
PGRES_SINGLE_TUPLE 
PGresult包含一个来自当前命令的结果元组。 这个状态只在查询选择了单行模式时发生

注意事项

请注意，恰好检索到零行的SELECT命令仍然显示PGRES_TUPLES_OK。PGRES_COMMAND_OK用于永远不能返回行的命令（插入或更新，不带返回子句等）。PGRES_EMPTY_QUERY响应可能表明客户端软件存在bug。
状态为PGRES_NONFATAL_ERROR的结果永远不会由PQexec或其他查询执行函数直接返回，此类结果将传递给通知处理程序。

示例

请参见7.3.5示例章节。

VastbaseG100