Linux编程常用的函数（六） PGSQL编程

（六）PGSQL编程

1.PGconn *PQconnectdb(const char *conninfo);//与数据库服务器建立一个新的连接
conninfo可以包含的内容有：host,hostaddr, port, dbname, user, password, connect_timeout, options,tty,sslmode,requiressl,service
2.//与数据库服务器建立一个新的连接（PQconnectdb的前身）
PGconn *PQsetdbLogin(const char *pghost,//IP
            const char *pgport,//断口
            const char *pgoptions,// 发送给服务器的命令行选项
            const char *pgtty,//服务器日志的输出方向
            const char *dbName,//数据库名
            const char *login,//用户
                const char *pwd);//密码
3. PGconn *PQsetdb(char *pghost,char *pgport,     char *pgoptions,char *pgtty,char *dbName);//与数据库服务器建立一个新的连接
这是一个调用 PQsetdbLogin() 的宏，只是login和pwd参数用空（null ）代替。 提供这个函数是为了与非常老版本的程序兼容。
4. PGconn *PQconnectStart(const char *conninfo);
PostgreSQLPollingStatusType PQconnectPoll(PGconn *conn);
//与数据库服务器建立一个非阻塞的连接
5. PQconninfoOption *PQconndefaults(void);//返回缺省的连接选项
typedef struct PQconninfoOption
{
char   *keyword;   /* 选项的键字 */
char   *envvar;   /* 退守的环境变量名 */
char   *compiled; /* 退守的编译时缺省值 */
char   *val;     /* 选项的当前值，或者 NULL */
char   *label;   /* 连接对话里字段的标识 */
char   *dispchar; /* 在连接对话里为此字段显示的字符。
      数值有：
              ""     原样现实输入的数值
              "*"   口令字段 － 隐藏数值
              "D"   调试选项 － 缺省的时候不显示 */
  int   dispsize; /* 对话中字段的以字符计的大小 */
}PQconninfoOption;
6. void PQfinish(PGconn *conn);//关闭连接
7. void PQreset(PGconn *conn);//重建新的连接
8. //以非阻塞模式重置与服务器的通讯端口。
int PQresetStart(PGconn *conn);
PostgreSQLPollingStatusType PQresetPoll(PGconn *conn);
9. char *PQdb(const PGconn *conn);//返回连接的数据库名
10. char *PQuser(const PGconn *conn);//返回连接的用户名
11. char *PQpass(const PGconn *conn);//返回连接密码
12. char *PQhost(const PGconn *conn);//返回连接主机名
13. char *PQport(const PGconn *conn);//返回连接端口
14. char *PQtty(const PGconn *conn);//返回连接的调试控制台TTY
15. char *PQoptions(const PGconn *conn);//返回连接请求传递的命令行选项
16. ConnStatusType PQstatus(const PGconn *conn);//返回连接状态
  这个状态可以是一系列值之一。 不过，我们在一个异步连接过程外面只能看到其中的两个： CONNECTION_OK 或 CONNECTION_BAD。一个与数据库的成功的连接返回状态 CONNECTION_OK。 一次失败的企图用状态 CONNECTION_BAD 标识。 通常，一个 OK 状态将保持到 PQfinish，但是一个通讯失败可能会导致状态过早地改变为 CONNECTION_BAD 。这时应用可以试着调用 PQreset 来恢复。
17. PGTransactionStatusType PQtransactionStatus(const PGconn *conn);
//返回当前服务器的事务内状态。
状态可以是 PQTRANS_IDLE （当前空闲）， PQTRANS_ACTIVE （正在处理一个命令）， PQTRANS_INTRANS （空闲，在一个合法的事务块内），或者 PQTRANS_INERROR （空闲，在一个失败的事务块内）。如果连接有问题，则返回 PQTRANS_UNKNOWN。只有在一个查询发送给了服务器并且还没有完成的时候才返回 PQTRANS_ACTIVE。
18. const char *PQparameterStatus(const PGconn *conn, const char *paramName);// 查找服务器的一个当前参数设置
19. int PQprotocolVersion(const PGconn *conn);查询所使用的前/后端协议。
20. int PQserverVersion(const PGconn *conn);//返回服务器的版本
21. char *PQerrorMessage(const PGconn *conn);// 返回连接中操作产生的最近的错误信息。
22. int PQsocket(const PGconn *conn);// 获取与服务器连接的套接字的文件描述符编号。 一个有效的描述符应该是大于或等于 0；结果为 -1 表示当前没有与服务器的连接打开。 （在正常的操作中，这个结果不会改变，但是可能在启动或者重置的过程中变化。）
23. int PQbackendPID(const PGconn *conn);// 返回处理此连接的服务器服务器的进程号ID（PID）。
24. SSL *PQgetssl(const PGconn *conn);// 返回连接使用的 SSL 结构，或者如果没有使用 SSL 的话返回 NULL。
25. PGresult *PQexec(PGconn *conn, const char *command);// 给服务器提交一条命令并且等待结果。
26. PGresult *PQexecParams(PGconn *conn,
              const char *command,
              int nParams,
              const Oid *paramTypes,
              const char * const *paramValues,
              const int *paramLengths,
              const int *paramFormats,
              int resultFormat);
//向服务器提交一条命令并且等待结果，还有额外的传递与 SQL 命令文本独立的参数的能力。
27. 用给定的参数提交请求，创建一个准备好的语句，然后等待结束。
PGresult *PQprepare(PGconn *conn,
            const char *stmtName,
            const char *query,
            int nParams,
            const Oid *paramTypes);
28. PGresult *PQexecPrepared(PGconn *conn,
                const char *stmtName,
                int nParams,
                const char * const *paramValues,
                const int *paramLengths,
                const int *paramFormats,
                int resultFormat);
//发送一个请求，执行一个带有给出参数的准备好的语句，并且等待结果。
29. 返回命令的结果状态。
ExecStatusType PQresultStatus(const PGresult *res);
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 发生了一个致命错误
30. char *PQresStatus(ExecStatusType status);// PQresStatus 把PQresultStatus返回的枚举类型转换成一个描述状态码的字符串常量。 调用者不应该释放结果。
31. char *PQresultErrorMessage(const PGresult *res);
  返回与查询关联的错误信息，或在没有错误时返回一个空字符串。
如果有错误，那么返回的字串将包括一个结尾的新行。调用者不应该直接释放结果。在相关的 PGresult 句柄传递给 PQclear 之后，它会自动释放。
32. char *PQresultErrorField(const PGresult *res, int fieldcode);
// 返回一个独立的错误报告字段。
33. void PQclear(PGresult *res);// PQclear 释放于PGresult相关联的存储空间。 任何不再需要的查询结果在不需要的时候都应该用PQclear释放掉。
34. PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
// 构造一个带有给出的状态的，空的PGresult对象。
35. int PQntuples(const PGresult *res)//返回查询结果里的行（元组）个数。 36. int PQnfields(const PGresult *res);
// 返回查询结果里数据行的数据域 （字段）的个数。
37. char *PQfname(const PGresult *res, int column_number);
// 返回与给出的数据域编号相关联的数据域（字段）的名称。数据域编号从 0 开始。调用者不应该直接释放结果。在相关联的 PGresult 句柄传递给 PQclear 之后，结果会被自动释放。
38. int PQfnumber(const PGresult *res,const char *column_name);
//返回与给出的数据域名称相关联的数据域（字段）的编号。
39. Oid PQftable(const PGresult *res, int column_number);
//返回我们抓取的字段所在的表的 OID。字段编号从 0 开始。
40. int PQftablecol(const PGresult *res, int column_number);
//返回组成声明的查询结果字段的字段号（在它的表内部）。查询结果字段编号从 0 开始，但是表字段编号不会是 0。
41. int PQfformat(const PGresult *res, int column_number);
  //返回说明给出字段的格式的格式代码。0开始
42. Oid PQftype(const PGresult *res, int column_number);
// 返回与给定数据域编号关联的数据域类型。 返回的整数是一个该类型的内部 OID 号。数据域编号从0 开始。
43. int PQfmod(const PGresult *res, int column_number);
// 返回与给定字段编号相关联的类型修饰词。 字段编号从 0 开始。
44. int PQfsize(const PGresult *res, int column_number);
//返回与给定字段编号关联的字段以字节计的大小。 字段编号从0 开始。
45. int PQbinaryTuples(const PGresult *res);
//如果PGresult包含二进制元组数据时返回 1如果包含 ASCII数据返回 0。
46. char *PQgetvalue(const PGresult *res,int row_number, int column_number);//返回一个PGresult 里面一行的单独的一个字段的值。
47. int PQgetisnull(const PGresult *res,int row_number, int column_number);
//测试一个字段是否为空（NULL）。行和字段编号从 0 开始。
48. int PQgetlength(const PGresult *res,int row_number,int column_number);//返回以字节计的字段的长度。行和字段编号从 0 开始。
49. char *PQcmdStatus(PGresult *res);
// 返回产生PGresult的 SQL 命令的命令状态字符串。
50. char *PQcmdTuples(PGresult *res);// 返回被 SQL 命令影响的行的数量。 51. Oid PQoidValue(const PGresult *res); // 返回一个插入的行的对象标识   （OID）—— 如果SQL 命令是INSERT，或者是一个包含合适 INSERT 语句的准 备好的 EXECUTE的时候。否则，函数返回 InvalidOid。如果受 INSERT 影响的 表不包含 OID， 也返回 InvalidOid。
52. char *PQoidStatus(const PGresult *res);//如果 SQL 命令是INSERT，或者包含合适 INSERT 的准备好语句 EXECUTE 了 。返回一个被插入的行的 OID 的字串。 （如果 INSERT 并非恰好插入一行，或者目标表没有OID，那么字串将是 0。） 如果命令不是INSERT，则返回一个空字串。
53. int PQsendQuery(PGconn *conn, const char *command);
//向服务器提交一个命令而不等待结果。 如果查询成功发送则返回 1，否则返回 0。 （此时，可以用PQerrorMessage获取关于失败的信息）。
54. int PQsendQueryParams(PGconn *conn,
              const char *command,
              int nParams,
              const Oid *paramTypes,
              const char * const *paramValues,
              const int *paramLengths,
              const int *paramFormats,
              int resultFormat);
// 给服务器提交一个命令和（命令需要的）分隔的参数，而不等待结果。
55. int PQsendPrepare(PGconn *conn, const char *stmtName, const char *query, int nParams, const Oid *paramTypes);
//发送一个请求，创建一个给定参数的准备好语句，而不等待结束。
56. int PQsendQueryPrepared(PGconn *conn,
                const char *stmtName,
                int nParams,
                const char * const *paramValues,
                const int *paramLengths,
                const int *paramFormats,
                int resultFormat);
//发送一个执行带有给出参数的准备好的语句的请求，不等待结果。
57. PGresult *PQgetResult(PGconn *conn);
//等待从前面 PQsendQuery，PQsendQueryParams， PQsendPrepare， 或者 PQsendQueryPrepared 调用返回的下一个结果， 然后返回之。当命令结束并且没有更多结果后返回 NULL。
58. int PQconsumeInput(PGconn *conn);
// 如果存在服务器来的输入可用，则使用之。
59. int PQisBusy(PGconn *conn);
// 在查询忙的时候返回 1 ，也就是说，PQgetResult 将阻塞住等待输入。一个 0 的返回表明这时调用 PQgetResult等以确保不阻塞
60. int PQsetnonblocking(PGconn *conn, int arg);// 把连接的状态设置为非阻塞。 如果arg为 1，把连接状态设置为非阻塞， 如果arg为 0， 把连接状态设置为阻塞。如果 OK 返回 0，如果错误返回 -1。
61. int PQisnonblocking(const PGconn *conn);
// 返回数据库连接的阻塞状态。 如果连接设置为非阻塞状态，返回 1，如果是阻塞状态返回 0。
62. int PQflush(PGconn *conn);
// 试图把任何正在排队的数据冲刷到服务器，如果成功（或者发送队列为空 ）返回 0，如果因某种原因失败返回 -1，或者是在无法把发送队列中的所有数据都发送出去，返回 1。（这种情况只有在连接不为阻塞模式的时候才会出现）。
63. PGcancel *PQgetCancel(PGconn *conn);// 创建一个数据结构，这个数据结构包含通过特定数据库连接取消一个命令所需要的信息。
64. void PQfreeCancel(PGcancel *cancel);
// 释放 PQgetCancel 创建的数据结构。
65. int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize);
// 要求服务器放弃处理当前命令。
66. int PQrequestCancel(PGconn *conn); //要求服务器放弃处理当前命令。