| PostgreSQL 8.3.3문서 | ||||
|---|---|---|---|---|
| Prev | Fast Backward | Chapter 29. libpq - C 라이브러리 | Fast Forward | Next |
PQexec함수는 일반적인 동기화 어플리케이션에 있어서 커맨드 전송에 적절한 것입니다.
그러나 일부의 유저에게 있어 중요한 문제가 될 수 있는 2개의 문제가 있습니다.
PQexec 는 커맨드가 완료할 때까지 대기합니다.
어플리케이션에 따라서는(예를 들면 유저 인터페이스의 보관과 같은) 그 밖에 실시해야 할 작업이 있습니다.
이 경우는 응답 대기로 차단되는 것을 원치 않습니다.
클라이언트 어플리케이션의 실행이 결과를 기다리고 있는 동안 정지되기 때문에, 어플리케이션으로 전송한 커맨드를 취소시키는 지시는 곤란합니다. (시그널 핸들러를 사용해 달성할 수 있지만, 다른 방법은 없습니다. )
PQexec가 반환할 수 있는 PGresult구조는 하나 뿐입니다.
만약 전송한 쿼리 문자열이 복수의SQL커맨드를 포함하고 있는 경우,
PQexec는 마지막 것만을 제외하고, 남아있는PGresult를 파기해 버립니다.
어플리케이션에게 이러한 제약이 바람직하지 않은 경우, 대신에PQexec를 구성하는 함수PQsendQuery와 PQgetResult를 사용해 주십시요.
또한, PQsendQueryParams와 PQsendPrepare, PQsendQueryPrepared, PQsendDescribePrepared, PQsendDescribePortal도 있어, PQgetResult를 사용하고, 각각PQexecParams와 PQprepare, PQexecPrepared, PQdescribePrepared, PQdescribePortal와 동일한 기능을 실시할 수 있습니다.
PQsendQuery
결과를 기다리는 일 없이, 서버에 커맨드를 발행합니다.
커맨드의 등록에 성공했을 경우 1이, 실패했을 경우 0이 반환됩니다.
(후자의 경우, PQerrorMessage 를 사용해 실패에 대한보다 많은 정보를 확인해 주십시요. )
int PQsendQuery(PGconn *conn, const char *command);
PQsendQuery호출이 성공하면, PQgetResult를 반복 호출해, 실행 결과를 취득합니다.
PQgetResult가 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와 같게 다루어집니다.
PQexecPrepared같이, 이것은 2.0 프로토콜에서는 동작하지 않습니다.
PQsendDescribePrepared
지정한 준비된 문장에 관한 정보 입수 요구를 보냅니다. 입수 완료까지 대기하지 않습니다.
int PQsendDescribePrepared(PGconn *conn, const char *stmtName);
이것은PQdescribePrepared의 비동기화입니다.
요구 접수가 가능하면 1이 반환됩니다. 불가능하면 0이 반환됩니다.
호출에 성공한 후, PQgetResult를 호출해 결과를 입수해 주십시요.
이 함수의 파라미터는 PQdescribePrepared와 같이 다루어집니다.
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는 단지 null 포인터를 반환합니다. )
PQgetResult의 null 이외의 결과는 각각 전에 살펴 본PGresult엑세서 함수를 사용해 처리되야 합니다.
각 결과 오브젝트에 대한 처리가 끝나면, 그 오브젝트를PQclear를 사용해 해제하는 것을 잊지 말아 주십시요.
커맨드가 활동 중이고, 필요한 응답 데이터가 아직PQconsumeInput로 읽히지 않은 경우만, PQgetResult가 차단하는 것을 주의하십시요.
PQsendQuery와 PQgetResult를 사용하는 것으로PQexec의 문제 중 하나는 해결됩니다.
즉, 커맨드가 복수의SQL커맨드를 포함하고 있는 경우에서도, 이러한 커맨드의 결과를 독립적으로 얻을 수 있는 것입니다
(이것은 다중처리를 심플한 형태로 처리합니다.
클라이언트는 같은 커맨드 문자열에서 나중 쿼리가 아직 처리 중인 동안에도 먼저 완료된 커맨드의 결과를 다룰 수 있습니다.
그러나 서버가 다음의SQL커맨드 처리에 들어가면, 그것이 완료할 때까지 역시PQgetResult 호출이 프론트엔드를 차단해 버립니다.
2개 이상의 함수를 잘 사용해 이것을 막을 수 있습니다.
PQconsumeInput
서버로부터 입력이 가능할 경우하게 되었을 경우, 그것을 파괴합니다.
int PQconsumeInput(PGconn *conn);
PQconsumeInput는 보통, "에러 없음"을 나타내는 1을 돌려주지만, 장애가 있을 경우 0을 반환합니다.
(이 경우는 PQerrorMessage를 참고해 주십시요. )
이 결과는 어떠한 입력 데이터가 실제로 수집되었는지를 나타내고 있는 것이 아닌 것에 주의하십시요.
PQconsumeInput의 호출 후, 어플리케이션은PQisBusy나 필요할 경우PQnotifies를 호출해 상태에 변화가 없는지를 조사할 수 있습니다.
PQconsumeInput는 결과나 통보를 취급하도록 아직 준비하지 않는 어플리케이션으로부터도 호출할 수 있습니다.
이 함수는 유효한 데이터를 읽어들여 버퍼에 보존하고, 결과적으로select에 의한 read 준비 완료 통보를 재설정 합니다
따라서 어플리케이션은PQconsumeInput를 사용하면select()의 검사 조건을 바로 지울 수 있기 때문에, 나머지는 천천히 결과를 조사하면 됩니다.
PQisBusy
쿼리가 복잡할 경우는 1을 리턴합니다. 즉,PQgetResult는 입력을 기다리기 위해 차단할 것입니다.
0이 리턴되면, PQgetResult를 호출해도 블록되지 않는 것을 보증합니다.
int PQisBusy(PGconn *conn);
PQisBusy자신은 서버로부터 데이터를 읽어들이는 조작을 하지 않습니다.
그러니까, 우선 최초로PQconsumeInput를 호출할 필요가 있습니다.
그렇게 하지 않으면 Busy 상태가 언제까지나 계속됩니다.
이러한 함수를 사용하는 어플리케이션은 보통, select()나 poll()를 사용하는 메인 루프를 가져, 대응해야 하는 모든 상태에 대기하고 있습니다.
하나의 조건은 서버로부터의 이용 가능한 입력일 것입니다.
이는 select()에 의하여 PQsocket로 식별되는 파일 기술자에서 읽어들일 수 있는 데이터가 있는 것을 의미합니다.
메인 루프가 입력 준비를 인지하면, 그 입력을 읽어들이기 위해PQconsumeInput를 호출해야 합니다.
그 다음 PQisBusy는, PQisBusy가 false(0)를 돌려주는 경우에PQgetResult도 호출할 수 있습니다.
또한, PQnotifies를 호출해, NOTIFY메세지( Section 29.7를 참조)를 검출할 수도 있습니다.
또한, PQsendQuery/PQgetResult를 사용하는 클라이언트는 서버에 의해 처리되는 커맨드에 대해서 취소를 시도할 수 있습니다.
Section 29.5를 참조해 주십시요.
그러나 PQcancel의 반환 값과 관계없이, 어플리케이션은PQgetResult를 사용한 보통의 결과 read 순서를 계속해야 합니다.
취소 절차의 성공은 단지, 그 커맨드를 보통 때보다 빨리 끝낼 뿐입니다.
위에서 설명한 함수를 사용하고, 데이터베이스 서버로부터의 입력 기다리는 블록을 실시하지 끝낼 수 있습니다. 그러나 아직, 서버로의 출력 전송을 기다리기 위해서 어플리케이션을 차단할 가능성이 있습니다. 이것은 비교적 드물게 발생하지만, 매우 긴 SQL 커맨드나 데이터 값이 전송되는 경우 발생할 수 있습니다. (그러나 어플리케이션이COPY IN를 거친 데이터를 전송하는 경우 자주 발생합니다. ) 이러한 가능성을 막고, 완전한 nonblock 데이터베이스 조작을 실시하기 위해서는 이하의 함수를 사용해 주십시요.
PQsetnonblocking
접속의 nonblock 상태를 설정합니다.
int PQsetnonblocking(PGconn *conn, int arg);
arg가 1의 경우, 접속 상태를 nonblock으로 설정합니다. arg가 0의 경우는 블록으로 설정합니다. 문제가 없으면 0이, 에러시는-1이 돌아갑니다.
nonblock 상태에서 PQsendQuery, PQputline, PQputnbytes와 PQendcopy의 호출은
차단되지 않습니다.
그러나 이들이 다시 호출될 필요가 있을 경우, 에러를 대신 리턴합니다.
PQexec는 nonblock 모드를 따르지 않습니다.
이 함수의 호출은 반드시 블록 방식에서 동작합니다.
PQisnonblocking
데이터베이스 접속의 블록 상태를 반환합니다.
int PQisnonblocking(const PGconn *conn);
접속이 nonblock 상태의 경우는 1이, 블록 상태의 경우는 0이 돌아갑니다.
PQflush
큐에 있었던 서버로의 출력 데이터를 쏟아내는 시도를 합니다. 성공시(또는, 전송 큐가 비었을 경우)는 0이 돌아갑니다. 어떠한 원인으로 실패했을 경우는 -1이, 전송 큐내의 데이터를 모두 전송할 수 없었던 경우는 1이 돌아갑니다. (이것은 접속이 nonblock 경우에만 발생합니다. )
int PQflush(PGconn *conn);
nonblock 접속시에는 커맨드나 데이터를 전송한 후에, PQflush를 호출해 주십시요.
1이 돌아갔을 경우, 소켓의 입력 준비가 될 때까지 기다리고, 재차 호출해 주십시요.
이것을 0이 리턴될 때까지 반복해 주십시요.
PQflush가 0을 돌려준 후에는 소켓의 read 준비가 될 때까지 기다리고, 위에서 설명한 바와 같이 응답을 읽어내 주십시요.