| PostgreSQL 8.3.3문서 | ||||
|---|---|---|---|---|
| Prev | Fast Backward | Chapter 29. libpq - C 라이브러리 | Fast Forward | Next |
PostgreSQL의COPY커맨드에서는 libpq가 사용하고 있는 네트워크 접속에 대해 읽어들이거나 입력을 선택할 수 있게 되어 있습니다. 본 절에서 설명하는 함수에 의해, 어플리케이션은 복사된 데이터의 제공이나 사용이 가능하다는 이점을 가집니다.
전체적인 처리로서 어플리케이션은 우선PQexec혹은 동등한 함수를 거친 COPY SQL 커맨드를 발행합니다.
(커맨드로 에러가 발생하지 않으면) 이 응답은 (지정한 복사 방향을 따라)PGRES_COPY_OUT나 PGRES_COPY_IN 상태 코드를 가진PGresult가 됩니다.
그 후, 어플리케이션은 본 절의 함수를 사용하고, 행 데이터를 수신하거나 전송해야 합니다.
데이터의 전송이 완료했을 때, 전송에 성공했는지 실패했는지를 나타내는 다른PGresult오브젝트가 반환됩니다.
그 상태는 성공시에는 PGRES_COMMAND_OK가 되고, 문제가 일어날 때는 PGRES_FATAL_ERROR가 됩니다.
이 시점에서, 다른 SQL 커맨드를PQexec를 거쳐서 발행할 수 있습니다.
(COPY조작 실행 중일 때, 같은 접속을 사용해 다른 SQL 커맨드를 실행할 수 없습니다. )
COPY커맨드가, 추가적으로 커맨드를 포함한 문자열로서PQexec를 거쳐 발행됐을 경우,
어플리케이션은COPY처리를 끝낸 후에, PQgetResult를 거친 결과를 계속 취득해야합니다.
PQexec커맨드 문자열이 완료되고, 그 후 커맨드가 안전하게 발행되는 것을 확실해지는 것은 PQgetResult가NULL를 반환할 때 뿐입니다.
본 절의 함수는 PQexec나 PQgetResult로부터PGRES_COPY_OUT나 PGRES_COPY_IN 결과 상태를 얻은 후에만 실행되어야 합니다.
이러한 상태 값 중 1개를 가지는 PGresult오브젝트는, 동작하는COPY조작에 관해 추가 데이터를 가집니다. 이 추가 데이터는 이하의 쿼리 결과를 가진 접속에서 사용되는 함수를 이용할 수 있습니다.
PQnfields
복사되는 열(필드) 수를 반환합니다.
PQbinaryTuples
0은 복사 전체 서식이 텍스트(새로운 행으로 단락지어진 행, 단락 문자로 단락지어진 열 등)인 것을 나타냅니다. 1은 복사 전체 서식이 바이너리인 것을 나타냅니다. 자세한 사항은 COPY 을 참조해 주십시요.
PQfformat
복사 조작의 각 열과 관계된 서식 코드(텍스트에서는 0, 바이너리에서는 1)를 반환합니다. 복사 전체 서식이 텍스트인 경우는 열 단위의 서식 코드는 항상 0입니다. 그러나 바이너리 서식은 텍스트열도 바이너리열도 서포트할 수 있습니다. (그러나 현재의COPY실행에서는 바이너리 복사에서만 바이너리 열이 발생합니다. 그 때문에, 현재 개별적인 열 서식은 항상 전체 서식과 일치합니다. )
Note: 이러한 추가 데이터 값는 프로토콜 3.0을 사용한 경우에 이용 가능합니다. 프로토콜 2.0을 사용하는 경우, 이러한 함수는 모두 0을 반환합니다.
이러한 함수는 COPY FROM STDIN기간에 데이터를 전송하기 위해서 사용됩니다. 접속이COPY_IN상태가 아닌데 호출될 경우, 이들은 실패합니다.
PQputCopyData
COPY_IN상태일 때, 서버로 데이터를 전송합니다.
int PQputCopyData(PGconn *conn,
const char *buffer,
int nbytes);
지정한buffer에 있는 COPY데이터를nbytes길이 만큼, 서버에 전송합니다.
데이터가 전송되었을 경우, 이 결과는 1이 됩니다.
데이터의 전송이 차단되어서 전송되지 않으면 0이 됩니다.
(이는 접속이 nonblock 모드의 경우에만 일어납니다. )
에러가 발생했을 경우는-1이 됩니다.
(반환 값이-1의 경우, 세부 사항을 얻기 위해서는 PQerrorMessage를 사용해 주십시요.
반환 값이 0인 경우는 입력 준비가 갖춰질 때까지 기다리고, 재실행해 주십시요. )
어플리케이션은COPY데이터 스트림을 사용하기 쉬운 크기의 버퍼로 나누어 읽어들일 수 있습니다. 전송시의 버퍼 로드 경계는 의미적인 중요성을 가지지 않습니다. 데이터 스트림 내용은 COPY 커맨드로 예상되는 데이터 서식과 일치할 필요가 있습니다. 자세한 사항은 COPY 을 참조해 주십시요.
PQputCopyEnd
COPY_IN상태일 때 서버로 데이터 종료 지시를 전송합니다.
int PQputCopyEnd(PGconn *conn,
const char *errormsg);
errormsg가NULL인 경우는 COPY_IN조작이 성공적으로 종료한 것입니다. errormsg가NULL이 아닌 경우는 COPY가 실패되도록 강요된 것입니다. errormsg가 지시하는 문자열은 에러 메세지로서 사용됩니다. (그러나 이 에러 메세지가 올바르게 서버에서 돌아간 것이라고 가정해야 하지는 않습니다. 서버는 이미 다른 원인으로COPY를 실패할 가능성이 있습니다. 또한, 이 강제적인 실패는 3.0 이전 프로토콜의 접속을 사용하고 있는 경우는 작동하지 않습니다. )
종료 데이터가 전송되었을 경우 결과는 1이 됩니다.
전송 시에 차단되어 전송할 수 없었던 경우는 0이 됩니다.
(이는 접속이 nonblock 모드의 경우에만 일어납니다.)
에러가 발생했을 경우는-1이 됩니다.
(반환 값이-1일 경우, 세부 사항을 얻기 위해서는 PQerrorMessage를 사용해 주십시요.
반환 값이 0인 경우는 입력이 준비될 때까지 기다리고, 재실행해 주십시요. )
PQputCopyEnd 호출에 성공한 후, PQgetResult를 호출해COPY커맨드의 최종적인 결과 상태를 꺼내 주십시요.
일반적인 방법으로 이 결과를 사용할 수 있을 때까지 대기합니다.
그리고 보통 연산으로 돌아옵니다.
이러한 함수는 COPY TO STDOUT동안 데이터를 받기 위해서 사용됩니다. COPY_OUT상태가 아닌 접속일 때 호출하면, 실패합니다.
PQgetCopyData
COPY_OUT상태 동안, 서버로부터 데이터를 수신합니다.
int PQgetCopyData(PGconn *conn,
char **buffer,
int async);
COPY기간 중, 서버로부터 다른 행 데이터의 입수를 시도합니다.
항상 1번에 1개의 행 데이터가 반환됩니다.
부분적인 행만이 이용 가능한 경우는 리턴되지 않습니다.
행 데이터의 취득합니다.는 것은 그 데이터를 보관하기 위한 메모리 체크의 할당을 의미합니다.
buffer파라미터는 NULL이 아니어야 합니다.
*buffer는 할당된 메모리 포인터에, 버퍼가 반환되지 않은 경우는 NULL로 설정됩니다.
NULL이 아닌 결과 버퍼는 더이상 필요 없어지면 PQfreemem를 사용해 해제해야 합니다.
행이 성공적으로 리턴되면, 반환 값은 행에 있는 데이터의 바이트 수가 됩니다.
(이것은 항상 0보다 커집니다. )
리턴된 문자열은 항상 null로 종료되지만, 텍스트COPY에서만 유용할 것입니다.
결과가 0이라는 것은 COPY가 진행 중이라는 것을 나타냅니다. 그러나 행은 아직 이용할 수 없는 상태라는 것을 나타냅니다.
(async가 true인 경우에만 발생할 수 있습니다.)
-1이라는 결과는 COPY가 완료된 것을 나타냅니다.
-2이라는 결과는 에러가 발생한 것을 나타냅니다.
(그 이유에 대해서는 PQerrorMessage를 참조해 주십시요. )
async가 true(0이 아닌)인 경우, PQgetCopyData는 입력을 기다리는 동안은 차단되지 않습니다.
COPY실행 중이어서 완료된 행을 꺼낼 수 없는 경우PQgetCopyData는 0을 반환합니다.
(이 경우, 재실행 전에 읽어들일 준비가 갖춰질 때까지 대기해 주십시요.
PQconsumeInput를 호출했는지는 관계 없습니다. )
async가 false(0)일 경우, PQgetCopyData는 데이터를 이용할 수 있을 때까지, 혹은 조작이 완료할 때까지 차단됩니다.
PQgetCopyData 가-1을 돌려준 후, PQgetResult를 호출해, COPY커맨드의 최종 결과 상태를 꺼내 주십시요.
일반적인 방법으로 결과를 이용할 수 있게 될 때까지 대기해도 상관하지 않습니다.
그리고 보통의 연산으로 돌아와 주십시요.
이하의 함수는 COPY를 취급하는 오래된 방법을 의미합니다. 이들은 여전히 동작하지만, 이들의 에러를 다루는데 미약하고, 데이터의 끝을 검출하는 방법이 불편하거나 바이너리나 nonbloking 이송의 지원이 부족하기 때문에 많이 사용되지 않습니다.
PQgetline
새 행으로 끝나는 문자열(서버로부터 전송된 것)을 length 크기 버퍼 문자열에 읽어들입니다.
int PQgetline(PGconn *conn,
char *buffer,
int length);
이 함수는 버퍼에length-1까지 문자를 복사하고, 끝나는 새로운 행을 0바이트로 옮겨놓습니다.
PQgetline 입력 끝에는 EOF를, 행 전체가 읽히면 0을 반환합니다.
끝나는 새로운 행이 아직 읽히지 않고, 버퍼가 가득찼을 경우, 1을 반환합니다.
어플리케이션은 새로운 행이, \. 2 문자인지 확인해야 합니다. 이 2 문자는 COPY커맨드 결과를 서버가 전송이 완료된 것을 나타냅니다. 어플리케이션이 만일length-1문자보다 긴 행을 받는 일에서도, 틀림없이\. 행을 인식합니다.는 확신이 필요합니다 (또 예를 들면 긴 데이터를 마지막 행으로 잡지 않도록 주의해 주세요).
PQgetlineAsync
COPY데이터행(서버로부터 전송된 것)을, 블로킹없이 버퍼에 읽어들입니다.
int PQgetlineAsync(PGconn *conn,
char *buffer,
int bufsize);
PQgetline와 유사하지만, COPY 데이터 비동기로, 즉 블로킹 없는 어플리케이션으로 사용할 수 있습니다.
COPY커맨드를 실행하고, PGRES_COPY_OUT응답을 받아들이면,
어플리케이션은 데이터 종료 신호를 받을 때까지PQconsumeInput와 PQgetlineAsync를 호출합니다.
PQgetline와 달리, 이 함수는 데이터 종료 검출에 대해서 책임을 가집니다.
PQgetlineAsync의 개개의 호출에서는 libpq의 입력 버퍼 내에서 완료된 행 데이터를 이용할 수 있는 경우에 데이터를 반환합니다.
반대의 경우, 행의 나머지가 도착할 때까지 데이터는 반환되지 않습니다.
이 함수는 복사 데이터의 종료를 나타내는 마크를 인식하면 -1을, 데이터에 아무것도 없으면 0을, 그리고 데이터를 돌려주는 경우는 그 바이트 수를 정의 값으로 반환합니다.
만약-1이 돌려주어지면, 호출측은 다음에PQendcopy를 호출해야 합니다.
그리고 보통 연산으로 돌아옵니다.
반환되는 데이터는 행 데이터의 경계를 넘어 확장되지 않습니다. 가능하면 행 전체를 한 번에 반환합니다. 그러나 호출한 곳에서 제공한 버퍼가 너무 작아서 서버로부터 보내지는 행을 보관할 수 없는 경우, 분할된 행 데이터를 반환합니다. 텍스트 데이터를 가지면 이것은 마지막 바이트가 \n인지 아닌지를 테스트해서 검출할 수 있습니다. (바이너리COPY의 경우에 같은 검출을 실시하기 위해서는 실제COPY데이터의 서식을 해석해야 합니다. ) 반환되는 문자열은 null로 끝나지 않습니다. (null로 끝나는 것을 추가합니다.면, 실제 확보하는 버퍼 크기를 bufsize보다 하나 작게 건네주십시요).
PQputline
서버에 null로 끝나는 문자열을 전송합니다. 문제 없으면 0을 반환합니다. 문자열 전송을 할 수 없는 경우 EOF를 반환합니다.
int PQputline(PGconn *conn,
const char *string);
PQputline 호출에 의해 전송되는 COPY데이터 스트림은 PQgetlineAsync로 리턴되는 서식과 같은 서식을 가집니다.
다만, 어플리케이션은 PQputline마다 정확히 1개의 데이터행을 전송하도록 강요당하지 않습니다.
호출마다 행의 일부나 복수의 행을 전송해도 문제 없습니다.
Note: PostgreSQL프로토콜 3.0 이전, 어플리케이션은 서버에 대해서COPY데이터 전송이 완료된 것을 통보하기 위해서, 최종 행으로서\. 2 문자를 명시적으로 전송할 필요가 있었습니다. 이것은 아직 동작합니다. 그러나 이것은 쓸모없게 되어 \. 의 특수한 의미는 향후 릴리스에서 없어질 것으로 예상됩니다. 실제 데이터 전송 완료 후에
PQendcopy를 호출하는 것은 중요합니다.
PQputnbytes
null로 끝나지 않는 문자열을 서버에 전송합니다. 문제 없으면 0을 반환합니다. 문자열 전송을 할 수 없는 경우,EOF를 반환합니다.
int PQputnbytes(PGconn *conn,
const char *buffer,
int nbytes);
이것은 확실히PQputline와 같습니다.
다만, 직접 전송 바이트 수를 지정하기 위해, null로 끝낼 필요가 없습니다.
바이너리 데이터를 전송할 때는 이 프로시저를 사용해 주십시요.
PQendcopy
서버와 동기화됩니다.
int PQendcopy(PGconn *conn);
이 함수는 서버가 복사를 완료할 때까지 기다립니다.
이 함수는 PQputline를 사용한 서버로의 문자열 전송이 완료된 시점, 혹은PGgetline를 사용한 서버로부터의 문자열 수신이 완료된 시점에서 호출해야 합니다.
이것을 발행하지 않으면 서버는 클라이언트와의"동기화가 어긋난"상태가 되어 버립니다.
이 함수로부터 돌아온 시점에서, 서버는 다음 SQL 커맨드를 받을 준비가 갖춰집니다.
정상적으로 종료됐을 경우, 반환된 값은 0입니다. 정상 종료가 아닐 경우는 0이 아닙니다.
(반환 값이 0이 아닐 경우, PQerrorMessage을 사용해 세부사항를 꺼내 주십시요. )
PQgetResult를 사용하는 경우, 어플리케이션은PQgetline를 반복 호출하고 PGRES_COPY_OUT에 응답해,
종료된 행을 찾아내면 계속해서 PQendcopy를 호출해야 합니다.
그리고PQgetResult가 null 포인터를 반환할 때까지, PQgetResult 루프로 돌아와야 합니다.
비슷하게, PGRES_COPY_IN는 연속한PQputline로 처리하고,PQendcopy를 호출한 뒤에 PQgetResult 루프로 돌아옵니다.
이러한 조정은 일련의SQL커맨드에 포함된 COPY커맨드를 확실하고, 올바르게 실행할 수 있을 것입니다.
비교적 오래된 어플리케이션에서는 COPY를PQexec로 실행하고, PQendcopy 실행으로 트랜잭션는 완료됩니다고 가정하는 일이 자주 있습니다.
이것은 커맨드 문자열 중의SQL가COPY뿐일 때만 올바르게 동작합니다.