Chapter 31. libpq - C Library
PQconsumeInput
can be called even if the application is not prepared to deal with a result or
notification just yet. The function will read available data and save it in a buffer, thereby causing
a
select()
read-ready indication to go away. The application can thus use
PQconsumeInput
to clear the
select()
condition immediately, and then examine the results at leisure.
PQisBusy
Returns 1 if a commandis busy, that is,
PQgetResult
would blockwaiting for input. A 0return
indicates that
PQgetResult
can be called with assurance of not blocking.
int PQisBusy(PGconn
*
conn);
PQisBusy
will not itself attempt toreaddata from the server; therefore
PQconsumeInput
must
be invoked first, or the busy state will never end.
Atypical application using these functions will have a main loop that uses
select()
or
poll()
to wait for all the conditions that it must respond to. One of the conditions will be input available
from the server, which in terms of
select()
means readable data on the file descriptor identified
by
PQsocket
.When the main loop detects input ready, it should call
PQconsumeInput
to read the
input. It can then call
PQisBusy
,followed by
PQgetResult
if
PQisBusy
returns false (0). It can
also call
PQnotifies
to detect
NOTIFY
messages (see Section 31.8).
Aclient that uses
PQsendQuery
/
PQgetResult
can also attempt to cancel a command that is still
being processed by the server; see Section 31.6. But regardless of the return value of
PQcancel
,the
applicationmust continuewith thenormal result-readingsequence using
PQgetResult
.A successful
cancellation will simply cause the commandto terminate sooner than it would have otherwise.
By using the functions described above, it is possible to avoid blocking while waiting for input from
thedatabase server. However, itis stillpossiblethatthe application willblockwaitingtosendoutput to
theserver. This is relatively uncommonbut canhappen if very longSQL commands or datavalues are
sent. (It is much more probable if the application sends data via
COPY IN
,however.) To prevent this
possibilityandachieve completely nonblocking database operation, the followingadditional functions
can be used.
PQsetnonblocking
Sets the nonblocking status of the connection.
int PQsetnonblocking(PGconn
*
conn, int arg);
Sets the state of the connection to nonblocking if
arg
is 1, or blocking if
arg
is 0. Returns 0 if
OK, -1 if error.
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.
Note that
PQexec
does not honor nonblocking mode; if itis called, itwill actin blockingfashion
anyway.
PQisnonblocking
Returns the blocking status of the database connection.
int PQisnonblocking(const PGconn
*
conn);
Returns 1 if the connection is set to nonblocking mode and 0 if blocking.
PQflush
Attempts to flush any queued output data to the server. Returns 0 if successful (or if the send
queue is empty), -1 if it failed for some reason, or 1 if it was unable to send all the data in the
688
Pdf insert image - insert images into PDF in C#.net, ASP.NET, MVC, Ajax, WinForms, WPF
Sample C# code to add image, picture, logo or digital photo into PDF document page using PDF page editor control
add jpg to pdf acrobat; add picture to pdf in preview
Pdf insert image - VB.NET PDF insert image library: insert images into PDF in vb.net, ASP.NET, MVC, Ajax, WinForms, WPF
Guide VB.NET Programmers How to Add Images in PDF Document
add image field to pdf form; how to add a jpeg to a pdf file
Chapter 31. libpq - C Library
send queue yet (this case can only occur if the connectionis nonblocking).
int PQflush(PGconn
*
conn);
After sending any command or data on a nonblocking connection, call
PQflush
.If it returns 1, wait
for the socket to become read- or write-ready. If it becomes write-ready, call
PQflush
again. If it
becomes read-ready, call
PQconsumeInput
,then call
PQflush
again. Repeatuntil
PQflush
returns
0. (It is necessary to check for read-ready and drain the input with
PQconsumeInput
,because the
server can block trying to send us data, e.g. NOTICE messages, and won’t read our data until we
read its.) Once
PQflush
returns 0, wait for the socket to be read-ready and then read the response as
described above.
31.5. Retrieving Query Results Row-By-Row
Ordinarily, libpq collects a SQL command’s entire result and returns it to the application as a single
PGresult
.This can beunworkable for commands thatreturna large number of rows. For such cases,
applications can use
PQsendQuery
and
PQgetResult
in single-row mode. In this mode, the result
row(s) are returned to the application one at a time, as they are received from the server.
To enter single-row mode, call
PQsetSingleRowMode
immediately after a successful call of
PQsendQuery
(or a sibling function). This mode selection is effective only for the currently
executing query. Then call
PQgetResult
repeatedly, until it returns null, as documented in Section
31.4. If the query returns any rows, they are returned as individual
PGresult
objects, which
look like normal query results except for having status code
PGRES_SINGLE_TUPLE
instead of
PGRES_TUPLES_OK
.After the last row, or immediately if the query returns zero rows, a zero-row
object with status
PGRES_TUPLES_OK
is returned; this is the signal that no more rows will arrive.
(But note that it is still necessary to continue calling
PQgetResult
until it returns null.) All of these
PGresult
objects will contain the same row description data (column names, types, etc) that an
ordinary
PGresult
object for the query would have. Each object should be freed with
PQclear
as
usual.
PQsetSingleRowMode
Select single-row mode for the currently-executing query.
int PQsetSingleRowMode(PGconn
*
conn);
This function canonly be calledimmediately after
PQsendQuery
or oneof its siblingfunctions,
before any other operation on the connection such as
PQconsumeInput
or
PQgetResult
.If
calledat thecorrecttime, thefunctionactivates single-rowmodefor thecurrentqueryandreturns
1. Otherwise the mode stays unchangedand the function returns 0. In any case, the mode reverts
to normal after completion of the current query.
689
VB.NET PDF Page Insert Library: insert pages into PDF file in vb.
Page: Insert PDF Pages. |. Home ›› XDoc.PDF ›› VB.NET PDF: Insert PDF Page.
acrobat insert image into pdf; add picture to pdf reader
C# PDF Image Extract Library: Select, copy, paste PDF images in C#
PDF ›› C# PDF: Extract PDF Image. How to C#: Extract Image from PDF Document. Support PDF Image Extraction from a Page, a Region on a Page, and PDF Document.
add image pdf document; add photo to pdf file
Chapter 31. libpq - C Library
Caution
Whileprocessingaquery, the server may return some rows andthenencounter
an error, causing the query to be aborted. Ordinarily, libpq discards any such
rows and reports only the error. But in single-row mode, those rows will have
already been returned to the application. Hence, the application will see some
PGRES_SINGLE_TUPLE PGresult
objectsfollowedbya
PGRES_FATAL_ERROR
ob-
ject. For proper transactionalbehavior, theapplication must be designed to dis-
card or undo whatever has been done with the previously-processed rows, if
the query ultimately fails.
31.6. Canceling Queries in Progress
Aclient application can request cancellation of a command that is still beingprocessed by the server,
using the functions described in this section.
PQgetCancel
Creates a data structure containing the information needed to cancel a command issued through
aparticular database connection.
PGcancel
*
PQgetCancel(PGconn
*
conn);
PQgetCancel
creates a
PGcancel
objectgivena
PGconn
connection object. Itwill return
NULL
if the given
conn
is
NULL
or an invalid connection. The
PGcancel
object is an opaque structure
that is not meant to be accessed directly by the application; it can only be passed to
PQcancel
or
PQfreeCancel
.
PQfreeCancel
Frees a data structure created by
PQgetCancel
.
void PQfreeCancel(PGcancel
*
cancel);
PQfreeCancel
frees a data object previously created by
PQgetCancel
.
PQcancel
Requests that the server abandon processing of the current command.
int PQcancel(PGcancel
*
cancel, char
*
errbuf, int errbufsize);
Thereturn value is 1if thecancel request was successfullydispatchedand 0if not. If not,
errbuf
is filled with an explanatory error message.
errbuf
must be a char array of size
errbufsize
(the recommended size is 256 bytes).
Successful dispatch is no guarantee that the request will have any effect, however. If the can-
cellation is effective, the current command will terminate early and return an error result. If the
cancellationfails (say, because the server was already doneprocessingthe command), then there
will be no visible result at all.
PQcancel
can safely be invoked from a signal handler, if the
errbuf
is a local variable in the
signal handler. The
PGcancel
object is read-only as far as
PQcancel
is concerned, so it can
also be invoked from a thread that is separate from the one manipulating the
PGconn
object.
690
C# PDF Page Insert Library: insert pages into PDF file in C#.net
Page: Insert PDF Pages. |. Home ›› XDoc.PDF ›› C# PDF: Insert PDF Page. C# PDF - Insert Blank PDF Page in C#.NET. Guide C#
acrobat add image to pdf; add a jpg to a pdf
VB.NET PDF Image Extract Library: Select, copy, paste PDF images
Home ›› XDoc.PDF ›› VB.NET PDF: Extract PDF Image. Support PDF Image Extraction from a Page, a Region on a Page, and PDF Document in VB.NET Project.
adding an image to a pdf in preview; adding an image to a pdf
Chapter 31. libpq - C Library
PQrequestCancel
PQrequestCancel
is a deprecated variant of
PQcancel
.
int PQrequestCancel(PGconn
*
conn);
Requests that the server abandon processing of the current command. It operates directly on the
PGconn
object, and in case of failure stores the error message in the
PGconn
object (whence it
can be retrieved by
PQerrorMessage
). Although the functionality is the same, this approach
creates hazards for multiple-thread programs and signal handlers, since it is possible that over-
writing the
PGconn
’s error message will mess up the operation currently in progress on the
connection.
31.7. The Fast-Path Interface
PostgreSQL provides a fast-path interface to send simple function calls to the server.
Tip: This interface is somewhat obsolete, as one can achieve similar performance and greater
functionality by setting up a prepared statement to define the function call. Then, executing the
statement with binary transmission of parameters and results substitutes for a fast-path function
call.
The function
PQfn
requests execution of a server function via the fast-path interface:
PGresult
*
PQfn(PGconn
*
conn,
int fnid,
int
*
result_buf,
int
*
result_len,
int result_is_int,
const PQArgBlock
*
args,
int nargs);
typedef struct
{
int len;
int isint;
union
{
int
*
ptr;
int integer;
} u;
} PQArgBlock;
The
fnid
argument is the OID of the function to be executed.
args
and
nargs
define the parameters
to be passed to the function; they must match the declared function argument list. When the
isint
field of a parameter structure is true, the
u.integer
value is sent to the server as an integer of the
indicated length (this must be 2 or 4 bytes); proper byte-swapping occurs. When
isint
is false, the
indicated number of bytes at
*
u.ptr
are sent with no processing; the data must be in the format
expected by the server for binary transmission of the function’s argument data type. (The declaration
of
u.ptr
as beingof type
int
*
is historical;itwouldbe better to consider it
void
*
.)
result_buf
points to the buffer in which to place the function’s return value. The caller must have allocated
691
C# PDF insert text Library: insert text into PDF content in C#.net
Text: Insert Text to PDF. |. Home ›› XDoc.PDF ›› C# PDF: Insert Text to PDF. C#.NET PDF SDK - Insert Text to PDF Document in C#.NET.
how to add a picture to a pdf document; adding images to pdf forms
C# Word - Insert Image to Word Page in C#.NET
Read: PDF Text Extract; C# Read: PDF Image Extract; C# Write: Insert text into PDF; C# Write: Add Image to PDF; C# Protect: Add Password
how to add image to pdf in acrobat; add photo to pdf form
Chapter 31. libpq - C Library
sufficient space to store the return value. (There is no check!) The actual result length in bytes will
be returned in the integer pointed to by
result_len
.If a 2- or 4-byte integer result is expected, set
result_is_int
to 1, otherwise set it to 0. Setting
result_is_int
to 1 causes libpq to byte-swap
the value if necessary, so that it is delivered as a proper
int
value for the client machine; note that a
4-byte integer is delivered into
*
result_buf
for either allowed result size. When
result_is_int
is 0, the binary-format byte string sent by the server is returned unmodified. (In this case it’s better to
consider
result_buf
as being of type
void
*
.)
PQfn
always returns avalid
PGresult
pointer. The resultstatus shouldbecheckedbefore the resultis
used. The caller is responsible for freeing the
PGresult
with
PQclear
when it is no longer needed.
Note that it is not possible to handle null arguments, null results, nor set-valued results when using
this interface.
31.8. Asynchronous Notification
PostgreSQL offers asynchronous notificationviathe
LISTEN
and
NOTIFY
commands. Aclient session
registers its interest in a particular notification channel with the
LISTEN
command (and can stop
listeningwith the
UNLISTEN
command). All sessions listeningon aparticular channelwill benotified
asynchronously when a
NOTIFY
command with that channel name is executed by any session. A
“payload” string can be passed to communicate additional data to the listeners.
libpq applications submit
LISTEN
,
UNLISTEN
,and
NOTIFY
commands as ordinary SQL commands.
The arrival of
NOTIFY
messages can subsequently be detected by calling
PQnotifies
.
The function
PQnotifies
returns the nextnotification from a listof unhandled notification messages
received from the server. It returns a null pointer if there are no pending notifications. Once a noti-
fication is returned from
PQnotifies
,it is considered handled and will be removed from the list of
notifications.
PGnotify
*
PQnotifies(PGconn
*
conn);
typedef struct pgNotify
{
char
*
relname;
/
*
notification channel name
*
/
int
be_pid;
/
*
process ID of notifying server process
*
/
char
*
extra;
/
*
notification payload string
*
/
} PGnotify;
After processing a
PGnotify
object returned by
PQnotifies
,be sure to free it with
PQfreemem
.It
is sufficient to free the
PGnotify
pointer; the
relname
and
extra
fields do not represent separate
allocations. (The names of these fields are historical; in particular, channel names need not have
anything to do with relation names.)
Example 31-2 gives a sample program that illustrates the use of asynchronous notification.
PQnotifies
does notactually read data from the server;it just returns messages previouslyabsorbed
by another libpq function. In prior releases of libpq, the only way to ensure timely receipt of
NOTIFY
messages was to constantly submit commands, even empty ones, and then check
PQnotifies
after
each
PQexec
.While this still works, it is deprecated as a waste of processing power.
Abetter way to check for
NOTIFY
messages when you have no useful commands to execute is to
call
PQconsumeInput
,then check
PQnotifies
.You can use
select()
to wait for data to arrive
from the server, thereby using no CPU power unless there is something to do. (See
PQsocket
to
obtain the file descriptor number to use with
select()
.) Note that this will work OK whether you
submit commands with
PQsendQuery
/
PQgetResult
or simply use
PQexec
.You should, however,
692
C# Create PDF from images Library to convert Jpeg, png images to
If you want to turn PDF file into image file format in C# application, then RasterEdge XDoc.PDF for .NET can also help with this.
add photo to pdf for; add jpg to pdf preview
C# PowerPoint - Insert Image to PowerPoint File Page in C#.NET
Read: PDF Text Extract; C# Read: PDF Image Extract; C# Write: Insert text into PDF; C# Write: Add Image to PDF; C# Protect: Add Password
add jpg to pdf; how to add image to pdf document
Chapter 31. libpq - C Library
remember to check
PQnotifies
after each
PQgetResult
or
PQexec
,to see if any notifications
came in during the processing of the command.
31.9. Functions Associated with the
COPY
Command
The
COPY
command inPostgreSQL has options to read from or write to the network connection used
bylibpq. Thefunctions describedinthis section allow applications to take advantage of this capability
by supplying or consuming copieddata.
The overall process is that the application first issues the SQL
COPY
command via
PQexec
or one of
theequivalent functions. Theresponse to this (if there is no error inthe command) willbea
PGresult
object bearing a status code of
PGRES_COPY_OUT
or
PGRES_COPY_IN
(depending on the specified
copy direction). Theapplicationshouldthenuse thefunctionsof this sectiontoreceiveor transmitdata
rows. Whenthe data transfer is complete, another
PGresult
object is returned to indicate success or
failure of the transfer. Its status will be
PGRES_COMMAND_OK
for success or
PGRES_FATAL_ERROR
if
some problem was encountered. At this point further SQL commands can be issued via
PQexec
.(It
is not possible to execute other SQL commands using the same connection while the
COPY
operation
is in progress.)
If a
COPY
command is issued via
PQexec
in a string that could contain additional commands, the
application must continue fetching results via
PQgetResult
after completing the
COPY
sequence.
Only when
PQgetResult
returns
NULL
is it certain that the
PQexec
command string is done and it
is safe to issue more commands.
The functions of this section should be executed only after obtaining a result status of
PGRES_COPY_OUT
or
PGRES_COPY_IN
from
PQexec
or
PQgetResult
.
A
PGresult
object bearing one of these status values carries some additional data about the
COPY
operation that is starting. This additional data is available using functions that are also used in con-
nection with query results:
PQnfields
Returns the number of columns (fields) to be copied.
PQbinaryTuples
0indicates the overall copy format is textual (rows separated by newlines, columns separated
by separator characters, etc). 1 indicates the overall copy format is binary. See COPY for more
information.
PQfformat
Returns the format code (0 for text, 1 for binary) associated with each column of the copy oper-
ation. The per-column format codes will always be zero when the overall copy format is textual,
but the binary format can support both text and binary columns. (However, as of the current im-
plementation of
COPY
,only binary columns appear in a binary copy; so the per-column formats
always match the overall format at present.)
Note: These additional data values are only available when using protocol 3.0. When using pro-
tocol 2.0, all these functions will return 0.
693
Chapter 31. libpq - C Library
31.9.1. Functions for Sending
COPY
Data
These functions are used to send data during
COPY FROM STDIN
.They will fail if called when the
connection is not in
COPY_IN
state.
PQputCopyData
Sends data to the server during
COPY_IN
state.
int PQputCopyData(PGconn
*
conn,
const char
*
buffer,
int nbytes);
Transmits the
COPY
data in the specified
buffer
,of length
nbytes
,to the server. The result
is 1 if the data was sent, zero if it was not sent because the attempt would block (this case
is only possible if the connection is in nonblocking mode), or -1 if an error occurred. (Use
PQerrorMessage
to retrieve details if the return value is -1. If the value is zero, wait for write-
ready and try again.)
The application can divide the
COPY
data stream into buffer loads of any convenient size. Buffer-
load boundaries have no semantic significance when sending. The contents of the data stream
must match the data format expected by the
COPY
command; see COPY for details.
PQputCopyEnd
Sends end-of-data indication to the server during
COPY_IN
state.
int PQputCopyEnd(PGconn
*
conn,
const char
*
errormsg);
Ends the
COPY_IN
operation successfully if
errormsg
is
NULL
.If
errormsg
is not
NULL
then
the
COPY
is forced to fail, with the string pointed to by
errormsg
used as the error message.
(One should not assume that this exact error message will come back from the server, however,
as the server might have alreadyfailed the
COPY
for its own reasons. Also note that the option to
force failure does not work when using pre-3.0-protocol connections.)
The result is 1 if the termination data was sent, zero if it was not sent because the attempt would
block (this case is only possible if the connection is in nonblocking mode), or -1 if an error
occurred. (Use
PQerrorMessage
to retrieve details if the return value is -1. If the value is zero,
wait for write-ready and try again.)
After successfully calling
PQputCopyEnd
,call
PQgetResult
to obtain the final result status of
the
COPY
command. One can wait for this result to be available in the usual way. Then return to
normal operation.
31.9.2. Functions for Receiving
COPY
Data
These functions are used to receive data during
COPY TO STDOUT
.They will fail if called when the
connection is not in
COPY_OUT
state.
PQgetCopyData
Receives data from the server during
COPY_OUT
state.
int PQgetCopyData(PGconn
*
conn,
char
**
buffer,
int async);
Attempts to obtain another row of data from the server during a
COPY
.Data is always returned
one data row at a time; if only a partial row is available, it is not returned. Successful return of a
694
Chapter 31. libpq - C Library
data row involves allocating a chunk of memory to hold the data. The
buffer
parameter must
be non-
NULL
.
*
buffer
is set to point to the allocated memory, or to
NULL
in cases where no
buffer is returned. A non-
NULL
result buffer should be freed using
PQfreemem
when no longer
needed.
When a rowis successfullyreturned, the return value is the number of data bytes in the row(this
will always be greater than zero). The returned string is always null-terminated, though this is
probablyonly useful for textual
COPY
.A resultof zero indicates that the
COPY
is still in progress,
but no rowis yetavailable (this is only possible when
async
is true). Aresult of -1 indicates that
the
COPY
is done. A result of -2 indicates that an error occurred (consult
PQerrorMessage
for
the reason).
When
async
is true (not zero),
PQgetCopyData
will not block waiting for input; it will return
zero if the
COPY
is still in progress but no complete row is available. (In this case wait for read-
ready and then call
PQconsumeInput
before calling
PQgetCopyData
again.) When
async
is
false (zero),
PQgetCopyData
will block until data is available or the operation completes.
After
PQgetCopyData
returns -1, call
PQgetResult
to obtain the finalresultstatusof the
COPY
command. One can wait for this result to be available in the usual way. Then return to normal
operation.
31.9.3. Obsolete Functions for
COPY
These functions represent older methods of handling
COPY
.Although they still work, they are depre-
cated due to poor error handling, inconvenient methods of detecting end-of-data, and lack of support
for binaryor nonblocking transfers.
PQgetline
Reads a newline-terminated line of characters (transmitted by the server) into a buffer string of
size
length
.
int PQgetline(PGconn
*
conn,
char
*
buffer,
int length);
This function copies up to
length
-1 characters into the buffer and converts the terminating
newline intoa zerobyte.
PQgetline
returns
EOF
atthe end of input, 0if the entire line has been
read, and 1 if the buffer is full but the terminating newline has not yet been read.
Note that the applicationmust check to see if a new line consists of the two characters
\.
,which
indicates that theserver has finished sending the results of the
COPY
command. If the application
might receive lines that are more than
length
-1 characters long, care is needed to be sure it
recognizes the
\.
line correctly (and does not, for example, mistake the end of a long data line
for a terminator line).
PQgetlineAsync
Reads a row of
COPY
data (transmitted by the server) into a buffer without blocking.
int PQgetlineAsync(PGconn
*
conn,
char
*
buffer,
int bufsize);
This function is similar to
PQgetline
, but it can be used by applications that must read
COPY
data asynchronously, that is, without blocking. Having issued the
COPY
command and
gotten a
PGRES_COPY_OUT
response, the application should call
PQconsumeInput
and
PQgetlineAsync
until the end-of-data signal is detected.
695
Chapter 31. libpq - C Library
Unlike
PQgetline
,this function takes responsibility for detecting end-of-data.
On each call,
PQgetlineAsync
will return data if a complete data row is available in libpq’s
input buffer. Otherwise, no data is returned until the rest of the rowarrives. The function returns
-1 if the end-of-copy-data marker has been recognized, or 0 if no data is available, or a positive
number giving the number of bytes of data returned. If -1 is returned, the caller must next call
PQendcopy
,and then return to normal processing.
The data returned will not extend beyond a data-row boundary. If possible a whole row will be
returned at one time. But if the buffer offered by the caller is too small to hold a row sent by the
server, then a partial data row will be returned. With textual data this can be detected by testing
whether the last returned byte is
\n
or not. (In a binary
COPY
,actual parsing of the
COPY
data
format will be needed to make the equivalent determination.) The returned string is not null-
terminated. (If you want to add a terminating null, be sure to pass a
bufsize
one smaller than
the room actually available.)
PQputline
Sends a null-terminated string to the server. Returns 0 if OKand
EOF
if unable to sendthe string.
int PQputline(PGconn
*
conn,
const char
*
string);
The
COPY
data stream sent bya series of callsto
PQputline
has thesameformatas that returned
by
PQgetlineAsync
,except that applications are not obliged to send exactly one data row per
PQputline
call; it is okay to send a partial line or multiple lines per call.
Note: Before PostgreSQL protocol3.0, it was necessary for the application toexplicitly send
thetwo characters
\.
as afinalline to indicate to theserver that it hadfinishedsending
COPY
data. While this stillworks, it is deprecatedandthe special meaningof
\.
canbeexpectedto
be removed in a future release. It is sufficient to call
PQendcopy
after having sent the actual
data.
PQputnbytes
Sends a non-null-terminated string to the server. Returns 0 if OK and
EOF
if unable to send the
string.
int PQputnbytes(PGconn
*
conn,
const char
*
buffer,
int nbytes);
This is exactly like
PQputline
,except that the data buffer need not be null-terminatedsince the
number of bytes to send is specified directly. Use this procedure when sending binary data.
PQendcopy
Synchronizes with the server.
int PQendcopy(PGconn
*
conn);
This function waits until the server has finished the copying. It should either be issued when the
laststring has been sent to the server using
PQputline
or when the laststring has been received
from the server using
PGgetline
.It must be issued or the server will get “out of sync” with
the client. Upon return from this function, the server is ready to receive the next SQL command.
The return value is 0 on successful completion, nonzero otherwise. (Use
PQerrorMessage
to
retrieve details if the return value is nonzero.)
When using
PQgetResult
,the application should respond to a
PGRES_COPY_OUT
result by
executing
PQgetline
repeatedly, followed by
PQendcopy
after the terminator line is seen. It
696
Chapter 31. libpq - C Library
shouldthenreturnto the
PQgetResult
loopuntil
PQgetResult
returns a nullpointer. Similarly
a
PGRES_COPY_IN
result is processed bya series of
PQputline
calls followed by
PQendcopy
,
then return to the
PQgetResult
loop. This arrangement will ensure that a
COPY
command em-
bedded in a series of SQL commands will be executed correctly.
Older applications are likely to submit a
COPY
via
PQexec
and assume that the transaction is
done after
PQendcopy
.This will work correctly only if the
COPY
is the only SQL command in
the command string.
31.10. Control Functions
These functions control miscellaneous details of libpq’s behavior.
PQclientEncoding
Returns the client encoding.
int PQclientEncoding(const PGconn
*conn
);
Note that it returns the encoding ID, not a symbolic string such as
EUC_JP
.If unsuccessful, it
returns -1. To convert an encoding ID to an encoding name, you canuse:
char
*
pg_encoding_to_char(int
encoding_id
);
PQsetClientEncoding
Sets the client encoding.
int PQsetClientEncoding(PGconn
*conn
, const char
*encoding
);
conn
is aconnectiontotheserver, and
encoding
is theencoding youwant to use. If the function
successfullysets the encoding, itreturns 0, otherwise-1. The current encodingfor this connection
can be determined by using
PQclientEncoding
.
PQsetErrorVerbosity
Determines the verbosity
of messages returned
by
PQerrorMessage
and
PQresultErrorMessage
.
typedef enum
{
PQERRORS_TERSE,
PQERRORS_DEFAULT,
PQERRORS_VERBOSE
} PGVerbosity;
PGVerbosity PQsetErrorVerbosity(PGconn
*
conn, PGVerbosity verbosity);
PQsetErrorVerbosity
sets the verbosity mode, returning the connection’s previous setting.
In TERSE mode, returned messages include severity, primary text, and position only; this will
normally fit on a single line. The default mode produces messages that include the above plus
any detail, hint, or context fields (these mightspan multiple lines). The VERBOSE mode includes
all available fields. Changing the verbosity does not affect the messages available from already-
existing
PGresult
objects, only subsequently-created ones.
PQtrace
Enables tracing of the client/server communication to a debugging file stream.
void PQtrace(PGconn
*
conn, FILE
*
stream);
697
Documents you may be interested
Documents you may be interested