PQescapeBytea documentation patch

We can fix any cross-reference later. I am applying any reasonable doc
changes and /contrib change by authors right away because we don't have
time for delay.

Patch applied. Thanks.

---------------------------------------------------------------------------

Here's a patch adding documentation for the PQescapeBytea function to
libpq.sgml

I was trying (but gave up) to cross-reference back to the input escape
table in the User's Guide, but could not get the documentation to
compile with a cross-book xref (missing IDREF error). Can a cross-book
xref be done?

Thanks,

Joe

[ text/html is unsupported, treating like TEXT/PLAIN ]

*** sgml.orig/libpq.sgml	Sun Nov 18 19:58:23 2001
--- sgml/libpq.sgml	Tue Nov 20 12:16:30 2001
***************
*** 903,908 ****
--- 903,958 ----
</para>
</sect2>

+ 
+  <sect2 id="libpq-exec-escape-bytea">
+   <title>Escaping binary strings for inclusion in SQL queries</title>
+   <indexterm zone="libpq-exec-escape-bytea">
+    <primary>escaping binary strings</primary>
+   </indexterm>
+   <para>
+    <function>PQescapeBytea</function>
+    Escapes a binary string (bytea type) for use within an SQL query.
+    <synopsis>
+     unsigned char *PQescapeBytea(unsigned char *from,
+                                          size_t from_length,
+                                          size_t *to_length);
+    </synopsis>
+ 
+    Certain <acronym>ASCII</acronym> characters MUST be escaped (but all
+    characters MAY be escaped) when used as part of a <type>BYTEA</type>
+    string literal in an <acronym>SQL</acronym> statement. In general, to
+    escape a character, it is converted into the three digit octal number
+    equal to the decimal <acronym>ASCII</acronym> value, and preceeded by
+    two backslashes. The single quote (') and backslash (\) characters have
+    special alternate escape sequences. See the Binary String data type
+    in the User's Guide for more information. <function>PQescapeBytea
+    </function> performs this operation, escaping only the minimally
+    required characters.
+   </para>
+ 
+   <para>
+    The <parameter>from</parameter> parameter points to the first
+    character of the string that is to be escaped, and the
+    <parameter>from_length</parameter> parameter reflects the number of
+    characters in this binary string (a terminating NUL character is
+    neither necessary nor counted).  The <parameter>to_length</parameter>
+    parameter shall point to a buffer suitable to hold the resultant
+    escaped string length. The result string length does not
+    include the terminating NUL character of the result.
+   </para>
+ 
+   <para>
+    <function>PQescapeBytea</> returns an escaped version of the
+    <parameter>from</parameter> parameter binary string, to a caller
+    provided buffer. The return string has all special characters replaced
+    so that they can be properly processed by the PostgreSQL string literal
+    parser, and the <type>bytea</type> input function. A terminating NUL
+    character is also added.  The single quotes that must surround
+    PostgreSQL string literals are not part of the result string.
+   </para>
+  </sect2>
+ 
+ 
<sect2 id="libpq-exec-select-info">
<title>Retrieving SELECT Result Information</title>

---------------------------(end of broadcast)---------------------------
TIP 3: if posting/reading through Usenet, please send an appropriate
subscribe-nomail command to majordomo@postgresql.org so that your
message can get through to the mailing list cleanly

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

[ redirected from patches to pgsql-docs ]

Joe Conway <joseph.conway@home.com> writes:

I was trying (but gave up) to cross-reference back to the input escape
table in the User's Guide, but could not get the documentation to
compile with a cross-book xref (missing IDREF error). Can a cross-book
xref be done?

AFAIK, not. If you look around you'll notice a bunch of vague cross-
references like

See the <citetitle>Administrator's Guide</> for details.

This pretty much sucks but as long as we maintain the notion that the
books should be separately buildable, I'm not sure there's a way to do
better.

As far as readers go, I don't see that there's any need for anything
but the integrated document --- and we could do better cross-references
in that setting than we are doing. The one good thing about the
separate books is that you can build just one (to check the markup of
a section you're working on) in a reasonable amount of time. Building
the integrated doc seems to take forever :-(

Anyone see a way out of this dilemma?

regards, tom lane

Tom Lane wrote:

AFAIK, not. If you look around you'll notice a bunch of vague cross-
references like

See the <citetitle>Administrator's Guide</> for details.

This pretty much sucks but as long as we maintain the notion that the
books should be separately buildable, I'm not sure there's a way to do
better.

I did find a reference to a docbook tag which *might* be useful, if we
can figure out how to use it. See:

http://www.oasis-open.org/docbook/documentation/reference/html/olink.html

The TargetDocEnt parameter seems to be defined in filelist.sgml, but it
isn't clear to me what the other parameters should be.

Joe

On Tue, Nov 20, 2001 at 12:21:00PM -0800, Joe Conway wrote:

Here's a patch adding documentation for the PQescapeBytea function to
libpq.sgml

...
+    <function>PQescapeBytea</function>
+    Escapes a binary string (bytea type) for use within an SQL query.
+    <synopsis>
+     unsigned char *PQescapeBytea(unsigned char *from,
+                                          size_t from_length,
+                                          size_t *to_length);

This makes me wonder: should libpq contain a function to do the opposite
too? eg.

string=GetValue(from a bytea type column)
PQunescapeBytea(string, some buffer, buffer's size)

- or is there already another way of doing it?

It seems to me that anyone using bytea with libpq will end up having
to reinvent this wheel. (Something worthy of being knocked up in my
Copious Free Time (tm))

Cheers,

Patrick

Patrick Welche wrote:

This makes me wonder: should libpq contain a function to do the opposite
too? eg.

string=GetValue(from a bytea type column)
PQunescapeBytea(string, some buffer, buffer's size)

- or is there already another way of doing it?

It seems to me that anyone using bytea with libpq will end up having
to reinvent this wheel. (Something worthy of being knocked up in my
Copious Free Time (tm))

I thought about that, but did not write it for a couple of reasons:

First, there wasn't a strong consensus that this type of function
belonged as part of libpq in the first place, so I didn't want to push
my luck ;-)

Second, at least in my current work, I'm using binary cursors, in which
case no unescaping is necessary.

I do agree that a standard bytea unescape function should be available
in the client library somewhere. Maybe for 7.3 . . .

Joe

Joe Conway writes:

I did find a reference to a docbook tag which *might* be useful, if we
can figure out how to use it. See:

http://www.oasis-open.org/docbook/documentation/reference/html/olink.html

The TargetDocEnt parameter seems to be defined in filelist.sgml, but it
isn't clear to me what the other parameters should be.

In theory, <olink> would be the right solution, but it requires you to
declare all the possible links explicitly beforehand, and at a place which
is not near your actual link. I think this would be much too complicated
to set up and maintain.

It's currently possible to do cross-document links like this:

| For more information, see <![%set-of-books;[<xref
| linkend="whereever">]]><![%single-book;[the <citetitle>Administrator's
| Guide</citetitle>]]>.

(Think of this as equivalent to #ifdef's.)

However, this is pretty ugly, and I think we don't want to expand too much
on this mechanism because it doesn't work in XML.

I imagine we could work out a solution which works like this: <xref
linkend="somewhere" role="if-missing:<citetitle>Administrator's
Guide</citetitle>"> (the role attribute is available for arbitrary
customization, which we'd need to write), but the trick is that ID
checking is done during the SGML parsing stage, which is before stylesheet
processing, so that you'd still get warnings (errors?) about undefined
ids. Possibly, we could convince the olink element to fit this idea, but
then we'd need to write the entire olink processing anew.

So, a short-term solution isn't in sight.

--
Peter Eisentraut peter_e@gmx.net

Hi Guys,
I have just begun coding in tcl/tk and hence sorry for this
simple question.
I am using tcl8.3 / tk8.3 and postgreSQL 7.3 . I am not able to
load pgtclsh library into to my TK application for giving it backend
support.
Can you please suggest me how to proceed?

Thanks,
Amit
----- Original Message -----
From: "Patrick Welche" <prlw1@newn.cam.ac.uk>
To: "Joe Conway" <joseph.conway@home.com>
Cc: <pgsql-interfaces@postgresql.org>
Sent: Wednesday, November 21, 2001 9:25 PM
Subject: Re: [INTERFACES] [PATCHES] PQescapeBytea documentation patch

"Amit Padgaonkar" <amit@nsat.co.jp> writes:

I am using tcl8.3 / tk8.3 and postgreSQL 7.3 . I am not able to
load pgtclsh library into to my TK application for giving it backend
support.

pgtclsh is not a library, it is a prebuilt tclsh application with the
libpgtcl library already loaded into it. You can load the libpgtcl
library into your own application with the usual Tcl "load" command.
pgaccess does it like so:

if {[info exists env(PGLIB)]} {
set libpgtclpath [file join $env(PGLIB) libpgtcl]
} else {
set libpgtclpath {libpgtcl}
}
load ${libpgtclpath}[info sharedlibextension]

regards, tom lane

Tom Lane wrote:

"Amit Padgaonkar" <amit@nsat.co.jp> writes:

I am using tcl8.3 / tk8.3 and postgreSQL 7.3 . I am not able to
load pgtclsh library into to my TK application for giving it backend
support.

pgtclsh is not a library, it is a prebuilt tclsh application with the
libpgtcl library already loaded into it. You can load the libpgtcl
library into your own application with the usual Tcl "load" command.
pgaccess does it like so:

if {[info exists env(PGLIB)]} {
set libpgtclpath [file join $env(PGLIB) libpgtcl]
} else {
set libpgtclpath {libpgtcl}
}
load ${libpgtclpath}[info sharedlibextension]

regards, tom lane

I use to have a directory .../tcl8.x/lib/pgtcl where I put a
symlink to the libpgtcl.so and the appropriate pgkIndex.tcl
file. The pgkIndex can be created by cd'ing into that
directory, starting a tclsh and issuing the command

pkg_mkIndex . ./libpgtcl.so

Once you have that, your Tcl scripts just need to do a

package require Pgtcl

No need for the user to set PGLIB or even know where it is
installed.

Jan

--

#======================================================================#
# It's easier to get forgiveness for being wrong than for being right. #
# Let's break this rule - forgive me. #
#================================================== JanWieck@Yahoo.com #

_________________________________________________________
Do You Yahoo!?
Get your free @yahoo.com address at http://mail.yahoo.com

Hi all,

I am using the PGLIB C lib to connect to PgSql to finish the query of
the GEOMETRY of a table.

At first, everything was OK. I could insert, update, delete and select of
whatever I wanted while the geometry data was small one.

So I wanted to try a bigger one. I uploaded a ESRI shape file into database
which was in the attachment --- Canada.sql. Then I tried the query.

res = PQexec(conn, "DECLARE mycursor BINARY CURSOR FOR select gid, name,
asbinary(the_geom) from canada");

if (!res || PQresultStatus(res) != PGRES_COMMAND_OK)
{
fprintf(stderr, "DECLARE CURSOR command failed\n");
PQclear(res);
exit_nicely(conn);
}
PQclear(res);

res = PQexec(conn, "FETCH ALL in mycursor");
if (!res || PQresultStatus(res) != PGRES_TUPLES_OK)
{
fprintf(stderr, "FETCH ALL command didn't return tuples
properly\n");
PQclear(res);
exit_nicely(conn);
}

Then I got the error when try to "FETCH ALL in mycursor".

Could you help me to figure out the problem? Thanks. I have attached
the files needed for you.

Best regards,
Tony

---
Tony Jiang, MSc
Research & Development Programmer/Analyst
MRF Geosystems Corp (www.mrf.com)
Suite 700, 665 8th Street SW,
Calgary, AB T2P 3K7
(403) 216-5515 ext:226