©
本文档使用
php.cn手册 发布
PQexec
函数对普通的同步应用里提交命令已经是足够用的了。但是它却有几个主要的缺陷,
而这些缺陷可能对某些用户很重要:
PQexec
等待命令结束。而应用可能还有其它的工作要做(比如维护用户界面等),
这个时候它可不想阻塞在这里等待相应。
因为客户端应用在等待结果的时候是处于挂起状态的,所以应用很难判断它是否该尝试结束正在进行的命令。 (这个事情可以在一个信号句柄中做,但是没别的方法。)
PQexec
只能返回一个PGresult结构。如果提交的命令字符串包含多个SQL命令,
除了最后一个PGresult以外都会被 PQexec 丢弃。
不想受到这些限制的应用可以改用下面的函数,这些函数也是构造PQexec
的函数:
也有PQsendQueryParams
,
PQsendPrepare
,
PQsendQueryPrepared
,
PQsendDescribePrepared
和
PQsendDescribePortal
,
他们可以和PQgetResult
一起使用,
分别用于复制PQexecParams
,
PQprepare
,
PQexecPrepared
,
PQdescribePrepared
和
PQdescribePortal
的功能。
PQsendQuery
向服务器提交一个命令而不等待结果。如果查询成功发送则返回 1,否则返回 0。
(此时,可以用PQerrorMessage
获取关于失败的信息)。
int PQsendQuery(PGconn *conn,const char *command);
在成功调用PQsendQuery
后,调用PQgetResult
一次或者多次获取结果
。在PQsendQuery
返回 NULL 指针,表明命令完成之前,
我们不能再调用PQsendQuery
(在同一次连接里)。
PQsendQueryParams
给服务器提交一个命令和(命令需要的)分隔的参数,而不等待结果。
int PQsendQueryParams(PGconn *conn, const char *command, int nParams, const Oid *paramTypes, const char * const *paramValues, const int *paramLengths, const int *paramFormats, int resultFormat);
这个等效于PQsendQuery
,只是查询参数可以和查询字串分开声明。
函数的参数处理和PQexecParams
一样。和PQexecParams
类似,它不能在 2.0 版本的协议连接上工作,
并且它只允许在查询字串里出现一条命令。
PQsendPrepare
发送一个请求,创建一个给定参数的准备好语句,而不等待结束。
int PQsendPrepare(PGconn *conn, const char *stmtName, const char *query, int nParams, const Oid *paramTypes);
这是PQprepare
的异步版本:如果它能发送这个请求,则返回 1,如果不能,则返回 0。
在成功调用之后,调用PQgetResult
判断服务器是否成功创建了准备好语句。
这个函数的参数的处理和PQprepare
一样。类似PQprepare
,
它不能在 2.0 版本协议的连接上运转。
PQsendQueryPrepared
发送一个执行带有给出参数的准备好的语句的请求,不等待结果。
int PQsendQueryPrepared(PGconn *conn, const char *stmtName, int nParams, const char * const *paramValues, const int *paramLengths, const int *paramFormats, int resultFormat);
这个函数类似PQsendQueryParams
,但是要执行的命令是通过给一个前面准备好的语句命名来声明的,
而不是给出一个查询字串。函数的参数处理和PQexecPrepared
一样。类似 PPQexecPrepared
,
它也不能在 2.0 版本的协议连接上跑。
PQsendDescribePrepared
发送一个执行带有给出参数的准备好的语句的请求,不等待结果。
int PQsendDescribePrepared(PGconn *conn,const char *stmtName);
这个函数类似PQdescribePrepared
,但是要执行的命令是通过给一个前面准备好的语句命名来声明的,
而不是给出一个查询字串。函数的参数处理和PQgetResult
一样。类似PQdescribePrepared
,
它也不能在 2.0 版本的协议连接上跑。
PQsendDescribePortal
发出请求,以获得关于制定端口的信息,不需要等待完成。
int PQsendDescribePortal(PGconn *conn,const char *portalName);
这是一个PQdescribePortal
的异步版本:
如果调度请求,那么返回1,否则返回0。成功调用之后,通过PQgetResult
获得结果。
函数参数处理与PQdescribePortal
相同。
类似于PQdescribePortal
,不能在2.0的协议连接上工作。
PQgetResult
等待从前面PQsendQuery
,
PQsendQueryParams
,
PQsendPrepare
或者PQsendQueryPrepared
调用返回的下一个结果,然后返回之。
当命令结束并且没有更多结果后返回 NULL。
PGresult *PQgetResult(PGconn *conn);
必须重复的调用PQgetResult
,直到它返回 NULL,表明该命令结束。(如果在没有活跃的命令时调用,
PQgetResult
将只是立即返回一个空指针。) 每个PQgetResult
返回的非 NULL 结
果都应该用前面描述的PGresult访问函数进行分析。不要忘了在结束分析后用PQclear
释放每个结果对象。注意,PQgetResult
只是在有一个命令是活跃的而且必须的返回数据还没
有被PQconsumeInput
读取时阻塞。
使用PQsendQuery
和PQgetResult
解决了PQexec
的一个问题:
如果一个命令字符串包含多个 SQL 命令,
这些命令的结果可以独立的获得。(顺便说一句:这样就允许一种简单的重叠处理模式,
客户端可以处理一个命令的结果而服务器可以仍然在处理同一命令字符串的后面的查询。)
但是,调用PQgetResult
将仍然导致前端被阻塞住直到服务器完成下一个SQL命令。
这一点可以通过合理的使用下面两个函数来避免:
PQconsumeInput
如果存在服务器来的输入可用,则使用之。
int PQconsumeInput(PGconn *conn);
PQconsumeInput
通常返回 1 表明"no error",而返回 0 表明有某种错误发生,
(这个时候可以用PQerrorMessage
)。注意这个结果并不表明实际上是否收集了数据。
在调用PQconsumeInput
,之后,应用可以检查PQisBusy
和/或PQnotifies
看一眼它们的状态是否改变。
PQconsumeInput
可以在应用还没有做好处理结果或通知的情况下被调用。这个函数将读取可用的数
据并且在一个缓冲区里保存它,这样导致一个select()
读准备好标识的生成。这样应用就可以使用
PQconsumeInput
立即清掉select()
条件,然后在空闲的时候检查结果。
PQisBusy
在查询忙的时候返回 1 ,也就是说,PQgetResult
将阻塞住等待输入。
一个 0 的返回表明这时调用PQgetResult
等以确保不阻塞。
int PQisBusy(PGconn *conn);
PQisBusy
本身将不会试图从服务器读取数据;所以必须先调用
PQconsumeInput
,否则忙状态将永远不会消除。
一个使用这些函数的典型的应用将有一个主循环使用select()
或poll()
等待所有它必须处理的条件。
其中一个条件将会是服务器来的数据已准备好,从select()
的角度
来看就是 PQsocket 标识的文件描述符上已经有可读取的数据。当主循环
侦测到输入准备好,它将调用PQconsumeInput
读取输入。然后可以调用PQisBusy
返回
false (0)后面可以跟着PQgetResult
。同样它(用户应用)可以调用PQnotifies
检测
NOTIFY信息(参阅下面的Section 31.7)。
一个使用PQsendQuery
//PQgetResult
的客户端同样也可以试图取消一个正在被服务
器处理的命令。参阅Section 31.5.。但是,不管PQcancel
,返回的值是多少,
应用都必须使用PQgetResult
进行正常的读取结果的动作序列。
一次成功的取消只会导致命令比正常情况下快些结束。
通过使用上面描述的函数,我们可以避免在等待来自数据库服务器的时候的阻塞。不过, 应用还是有可能阻塞在给服务器发送输出上。这种情况比较少见,但是也可能发生, 尤其是我们要发送非常长的 SQL 命令或者数据值的时候。(不过,最有可能的是在应用通 过COPY IN发送数据的时候。)为了避免这个可能性,实现完全的非阻塞数据库操作 ,我们可以使用下列额外的函数。
PQsetnonblocking
把连接的状态设置为非阻塞。
int PQsetnonblocking(PGconn *conn,int arg);
如果arg为 1,把连接状态设置为非阻塞,如果arg为 0,把连接状态设 置为阻塞。如果 OK 返回 0,如果错误返回 -1。
In the nonblocking state,calls to
PQsendQuery
,PQputline
,
PQputnbytes
,and
PQendcopy
will not block but instead return
an error if they need to be called again.
在非阻塞状态,调用PQsendQuery
,PQputline
,
PQputnbytes
,和
PQendcopy
的时候不被阻塞,
而是在如果需要再次调用它们时将返回一个错误。
请注意PQexec
不会在意任何非阻塞模式;如果调用了PQexec
,那么它的行为总是阻塞的。
PQisnonblocking
返回数据库连接的阻塞状态。
int PQisnonblocking(const PGconn *conn);
如果连接设置为非阻塞状态,返回 1,如果是阻塞状态返回 0。
PQflush
试图把任何正在排队的数据冲刷到服务器,如果成功(或者发送队列为空)返回 0, 如果因某种原因失败返回 -1,或者是在无法把发送队列中的所有数据都发送出去, 返回 1。(这种情况只有在连接不为阻塞模式的时候才会出现)。
int PQflush(PGconn *conn);
在一个非阻塞的连接上发送任何命令或者数据之后,调用PQflush
。如果返回 1,
就等待套接字写准备好然后再次调用;重复这个操作直到它返回 0。一旦PQflush
返回 0,
则等待套接字为读准备好,准备好之后就像上面那样读取。