annotate man/lispref/postgresql.texi @ 4407:4ee73bbe4f8e

Always use boyer_moore in ASCII or Latin-1 buffers with ASCII search strings. 2007-12-26 Aidan Kehoe <kehoea@parhasard.net> * casetab.c: Extend and correct some case table documentation. * search.c (search_buffer): Correct a bug where only the first entry for a character in the case equivalence table was examined in determining if the Boyer-Moore search algorithm is appropriate. If there are case mappings outside of the charset and row of the characters specified in the search string, those case mappings can be safely ignored (and Boyer-Moore search can be used) if we know from the buffer statistics that the corresponding characters cannot occur. * search.c (boyer_moore): Assert that we haven't been passed a string with varying characters sets or rows within character sets. That's what simple_search is for. In the very rare event that a character in the search string has a canonical case mapping that is not in the same character set and row, don't try to search for the canonical character, search for some other character that is in the the desired character set and row. Assert that the case table isn't corrupt. Do not search for any character case mappings that cannot possibly occur in the buffer, given the buffer metadata about its contents.
author Aidan Kehoe <kehoea@parhasard.net>
date Wed, 26 Dec 2007 17:30:16 +0100
parents f43f9ca6c7d9
children 9fae6227ede5
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1 @c -*-texinfo-*-
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
2 @c This is part of the XEmacs Lisp Reference Manual.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
3 @c Copyright (C) 2000 Electrotechnical Laboratory, JAPAN
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
4 @c Licensed to the Free Software Foundation
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
5 @c See the file lispref.texi for copying conditions.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
6 @c Thank you Oscar Figueiredo! This file was shamelessly cloned from
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
7 @c ldap.texi.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
8 @setfilename ../../info/postgresql.info
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
9 @node PostgreSQL Support, Internationalization, LDAP Support, top
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
10 @chapter PostgreSQL Support
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
11 @cindex PostgreSQL
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
12
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
13 XEmacs can be linked with PostgreSQL libpq run-time support to provide
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
14 relational database access from Emacs Lisp code.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
15
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
16 @menu
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
17 * Building XEmacs with PostgreSQL support::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
18 * XEmacs PostgreSQL libpq API::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
19 * XEmacs PostgreSQL libpq Examples::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
20 @end menu
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
21
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
22 @node Building XEmacs with PostgreSQL support, XEmacs PostgreSQL libpq API, ,PostgreSQL Support
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
23 @comment node-name, next, previous, up
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
24 @section Building XEmacs with PostgreSQL support
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
25
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
26 XEmacs PostgreSQL support requires linking to the PostgreSQL libpq
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
27 library. Describing how to build and install PostgreSQL is beyond the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
28 scope of this document. See the PostgreSQL manual for details.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
29
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
30 If you have installed XEmacs from one of the binary kits on
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
31 (@url{ftp://ftp.xemacs.org/}), or are using an XEmacs binary from a CD
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
32 ROM, you may have XEmacs PostgreSQL support by default. @code{M-x
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
33 describe-installation} will tell you if you do.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
34
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
35 If you are building XEmacs from source, you need to install PostgreSQL
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
36 first. On some systems, PostgreSQL will come pre-installed in /usr. In
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
37 this case, it should be autodetected when you run configure. If
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
38 PostgreSQL is installed into its default location,
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
39 @file{/usr/local/pgsql}, you must specify
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
40 @code{--site-prefixes=/usr/local/pgsql} when you run configure. If
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
41 PostgreSQL is installed into another location, use that instead of
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
42 @file{/usr/local/pgsql} when specifying @code{--site-prefixes}.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
43
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
44 As of XEmacs 21.2, PostgreSQL versions 6.5.3 and 7.0 are supported.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
45 XEmacs Lisp support for V7.0 is somewhat more extensive than support for
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
46 V6.5. In particular, asynchronous queries are supported.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
47
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
48 @node XEmacs PostgreSQL libpq API, XEmacs PostgreSQL libpq Examples, Building XEmacs with PostgreSQL support, PostgreSQL Support
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
49 @comment node-name, next, previous, up
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
50 @section XEmacs PostgreSQL libpq API
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
51
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
52 The XEmacs PostgreSQL API is intended to be a policy-free, low-level
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
53 binding to libpq. The intent is to provide all the basic functionality
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
54 and then let high level Lisp code decide its own policies.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
55
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
56 This documentation assumes that the reader has knowledge of SQL, but
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
57 requires no prior knowledge of libpq.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
58
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
59 There are many examples in this manual and some setup will be required.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
60 In order to run most of the following examples, the following code needs
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
61 to be executed. In addition to the data is in this table, nearly all of
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
62 the examples will assume that the free variable @code{P} refers to this
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
63 database connection. The examples in the original edition of this
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
64 manual were run against Postgres 7.0beta1.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
65
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
66 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
67 (progn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
68 (setq P (pq-connectdb ""))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
69 ;; id is the primary key, shikona is a Japanese word that
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
70 ;; means `the professional name of a Sumo wrestler', and
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
71 ;; rank is the Sumo rank name.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
72 (pq-exec P (concat "CREATE TABLE xemacs_test"
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
73 " (id int, shikona text, rank text);"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
74 (pq-exec P "COPY xemacs_test FROM stdin;")
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
75 (pq-put-line P "1\tMusashimaru\tYokuzuna\n")
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
76 (pq-put-line P "2\tDejima\tOozeki\n")
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
77 (pq-put-line P "3\tMusoyama\tSekiwake\n")
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
78 (pq-put-line P "4\tMiyabiyama\tSekiwake\n")
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
79 (pq-put-line P "5\tWakanoyama\tMaegashira\n")
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
80 (pq-put-line P "\\.\n")
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
81 (pq-end-copy P))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
82 @result{} nil
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
83 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
84
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
85 @menu
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
86 * libpq Lisp Variables::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
87 * libpq Lisp Symbols and DataTypes::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
88 * Synchronous Interface Functions::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
89 * Asynchronous Interface Functions::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
90 * Large Object Support::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
91 * Other libpq Functions::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
92 * Unimplemented libpq Functions::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
93 @end menu
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
94
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
95 @node libpq Lisp Variables, libpq Lisp Symbols and DataTypes, XEmacs PostgreSQL libpq API, XEmacs PostgreSQL libpq API
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
96 @comment node-name, next, previous, up
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
97 @subsection libpq Lisp Variables
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
98
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
99 Various Unix environment variables are used by libpq to provide defaults
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
100 to the many different parameters. In the XEmacs Lisp API, these
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
101 environment variables are bound to Lisp variables to provide more
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
102 convenient access to Lisp Code. These variables are passed to the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
103 backend database server during the establishment of a database
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
104 connection and when the @code{pq-setenv} call is made.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
105
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
106 @defvar pg:host
1738
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
107 Initialized from the @code{PGHOST} environment variable. The default
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
108 host to connect to.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
109 @end defvar
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
110
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
111 @defvar pg:user
1738
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
112 Initialized from the @code{PGUSER} environment variable. The default
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
113 database user name.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
114 @end defvar
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
115
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
116 @defvar pg:options
1738
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
117 Initialized from the @code{PGOPTIONS} environment variable. Default
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
118 additional server options.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
119 @end defvar
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
120
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
121 @defvar pg:port
1738
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
122 Initialized from the @code{PGPORT} environment variable. The default
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
123 TCP port to connect to.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
124 @end defvar
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
125
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
126 @defvar pg:tty
1738
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
127 Initialized from the @code{PGTTY} environment variable. The default
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
128 debugging TTY.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
129
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
130 Compatibility note: Debugging TTYs are turned off in the XEmacs Lisp
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
131 binding.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
132 @end defvar
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
133
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
134 @defvar pg:database
1738
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
135 Initialized from the @code{PGDATABASE} environment variable. The
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
136 default database to connect to.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
137 @end defvar
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
138
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
139 @defvar pg:realm
1738
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
140 Initialized from the @code{PGREALM} environment variable. The default
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
141 Kerberos realm.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
142 @end defvar
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
143
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
144 @defvar pg:client-encoding
1738
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
145 Initialized from the @code{PGCLIENTENCODING} environment variable. The
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
146 default client encoding.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
147
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
148 Compatibility note: This variable is not present in non-Mule XEmacsen.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
149 This variable is not present in versions of libpq prior to 7.0.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
150 In the current implementation, client encoding is equivalent to the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
151 @code{file-name-coding-system} format.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
152 @end defvar
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
153
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
154 @c unused
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
155 @defvar pg:authtype
1738
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
156 Initialized from the @code{PGAUTHTYPE} environment variable. The
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
157 default authentication scheme used.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
158
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
159 Compatibility note: This variable is unused in versions of libpq after
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
160 6.5. It is not implemented at all in the XEmacs Lisp binding.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
161 @end defvar
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
162
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
163 @defvar pg:geqo
1738
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
164 Initialized from the @code{PGGEQO} environment variable. Genetic
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
165 optimizer options.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
166 @end defvar
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
167
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
168 @defvar pg:cost-index
1738
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
169 Initialized from the @code{PGCOSTINDEX} environment variable. Cost
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
170 index options.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
171 @end defvar
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
172
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
173 @defvar pg:cost-heap
1738
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
174 Initialized from the @code{PGCOSTHEAP} environment variable. Cost heap
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
175 options.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
176 @end defvar
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
177
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
178 @defvar pg:tz
1738
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
179 Initialized from the @code{PGTZ} environment variable. Default
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
180 timezone.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
181 @end defvar
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
182
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
183 @defvar pg:date-style
1738
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
184 Initialized from the @code{PGDATESTYLE} environment variable. Default
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
185 date style in returned date objects.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
186 @end defvar
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
187
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
188 @defvar pg-coding-system
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
189 This is a variable controlling which coding system is used to encode
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
190 non-ASCII strings sent to the database.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
191
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
192 Compatibility Note: This variable is not present in InfoDock.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
193 @end defvar
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
194
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
195 @node libpq Lisp Symbols and DataTypes, Synchronous Interface Functions, libpq Lisp Variables, XEmacs PostgreSQL libpq API
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
196 @comment node-name, next, previous, up
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
197 @subsection libpq Lisp Symbols and Datatypes
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
198
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
199 The following set of symbols are used to represent the intermediate
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
200 states involved in the asynchronous interface.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
201
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
202 @defvr {Symbol} pgres::polling-failed
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
203 Undocumented. A fatal error has occurred during processing of an
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
204 asynchronous operation.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
205 @end defvr
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
206
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
207 @defvr {Symbol} pgres::polling-reading
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
208 An intermediate status return during an asynchronous operation. It
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
209 indicates that one may use @code{select} before polling again.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
210 @end defvr
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
211
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
212 @defvr {Symbol} pgres::polling-writing
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
213 An intermediate status return during an asynchronous operation. It
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
214 indicates that one may use @code{select} before polling again.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
215 @end defvr
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
216
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
217 @defvr {Symbol} pgres::polling-ok
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
218 An asynchronous operation has successfully completed.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
219 @end defvr
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
220
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
221 @defvr {Symbol} pgres::polling-active
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
222 An intermediate status return during an asynchronous operation. One can
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
223 call the poll function again immediately.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
224 @end defvr
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
225
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
226 @defun pq-pgconn conn field
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
227 @var{conn} A database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
228 @var{field} A symbol indicating which field of PGconn to fetch. Possible
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
229 values are shown in the following table.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
230 @table @code
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
231 @item pq::db
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
232 Database name
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
233 @item pq::user
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
234 Database user name
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
235 @item pq::pass
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
236 Database user's password
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
237 @item pq::host
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
238 Hostname database server is running on
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
239 @item pq::port
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
240 TCP port number used in the connection
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
241 @item pq::tty
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
242 Debugging TTY
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
243
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
244 Compatibility note: Debugging TTYs are not used in the XEmacs Lisp API.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
245 @item pq::options
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
246 Additional server options
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
247 @item pq::status
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
248 Connection status. Possible return values are shown in the following
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
249 table.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
250 @table @code
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
251 @item pg::connection-ok
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
252 The normal, connected status.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
253 @item pg::connection-bad
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
254 The connection is not open and the PGconn object needs to be deleted by
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
255 @code{pq-finish}.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
256 @item pg::connection-started
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
257 An asynchronous connection has been started, but is not yet complete.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
258 @item pg::connection-made
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
259 An asynchronous connect has been made, and there is data waiting to be sent.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
260 @item pg::connection-awaiting-response
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
261 Awaiting data from the backend during an asynchronous connection.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
262 @item pg::connection-auth-ok
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
263 Received authentication, waiting for the backend to start up.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
264 @item pg::connection-setenv
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
265 Negotiating environment during an asynchronous connection.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
266 @end table
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
267 @item pq::error-message
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
268 The last error message that was delivered to this connection.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
269 @item pq::backend-pid
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
270 The process ID of the backend database server.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
271 @end table
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
272 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
273
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
274 The @code{PGresult} object is used by libpq to encapsulate the results
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
275 of queries. The printed representation takes on four forms. When the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
276 PGresult object contains tuples from an SQL @code{SELECT} it will look
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
277 like:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
278
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
279 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
280 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
281 @result{} #<PGresult PGRES_TUPLES_OK[5] - SELECT>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
282 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
283
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
284 The number in brackets indicates how many rows of data are available.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
285 When the PGresult object is the result of a command query that doesn't
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
286 return anything, it will look like:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
287
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
288 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
289 (pq-exec P "CREATE TABLE a_new_table (i int);")
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
290 @result{} #<PGresult PGRES_COMMAND_OK - CREATE>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
291 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
292
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
293 When either the query is a command-type query that can affect a number
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
294 of different rows, but doesn't return any of them it will look like:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
295
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
296 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
297 (progn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
298 (pq-exec P "INSERT INTO a_new_table VALUES (1);")
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
299 (pq-exec P "INSERT INTO a_new_table VALUES (2);")
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
300 (pq-exec P "INSERT INTO a_new_table VALUES (3);")
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
301 (setq R (pq-exec P "DELETE FROM a_new_table;")))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
302 @result{} #<PGresult PGRES_COMMAND_OK[3] - DELETE 3>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
303 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
304
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
305 Lastly, when the underlying PGresult object has been deallocated
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
306 directly by @code{pq-clear} the printed representation will look like:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
307
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
308 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
309 (progn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
310 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
311 (pq-clear R)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
312 R)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
313 @result{} #<PGresult DEAD>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
314 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
315
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
316 The following set of functions are accessors to various data in the PGresult
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
317 object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
318
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
319 @defun pq-result-status result
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
320 Return status of a query result.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
321 @var{result} is a PGresult object. The return value is one of the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
322 symbols in the following table.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
323 @table @code
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
324 @item pgres::empty-query
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
325 A query contained no text. This is usually the result of a recoverable
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
326 error, or a minor programming error.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
327 @item pgres::command-ok
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
328 A query command that doesn't return anything was executed properly by
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
329 the backend.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
330 @item pgres::tuples-ok
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
331 A query command that returns tuples was executed properly by the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
332 backend.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
333 @item pgres::copy-out
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
334 Copy Out data transfer is in progress.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
335 @item pgres::copy-in
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
336 Copy In data transfer is in progress.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
337 @item pgres::bad-response
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
338 An unexpected response was received from the backend.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
339 @item pgres::nonfatal-error
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
340 Undocumented. This value is returned when the libpq function
1738
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
341 @code{PQresultStatus} is called with a @code{NULL} pointer.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
342 @item pgres::fatal-error
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
343 Undocumented. An error has occurred in processing the query and the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
344 operation was not completed.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
345 @end table
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
346 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
347
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
348 @defun pq-res-status result
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
349 Return the query result status as a string, not a symbol.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
350 @var{result} is a PGresult object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
351
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
352 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
353 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
354 @result{} #<PGresult PGRES_TUPLES_OK[5] - SELECT>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
355 (pq-res-status R)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
356 @result{} "PGRES_TUPLES_OK"
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
357 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
358 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
359
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
360 @defun pq-result-error-message result
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
361 Return an error message generated by the query, if any.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
362 @var{result} is a PGresult object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
363
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
364 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
365 (setq R (pq-exec P "SELECT * FROM xemacs-test;"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
366 @result{} <A fatal error is signaled in the echo area>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
367 (pq-result-error-message R)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
368 @result{} "ERROR: parser: parse error at or near \"-\"
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
369 "
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
370 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
371 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
372
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
373 @defun pq-ntuples result
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
374 Return the number of tuples in the query result.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
375 @var{result} is a PGresult object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
376
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
377 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
378 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
379 @result{} #<PGresult PGRES_TUPLES_OK[5] - SELECT>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
380 (pq-ntuples R)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
381 @result{} 5
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
382 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
383 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
384
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
385 @defun pq-nfields result
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
386 Return the number of fields in each tuple of the query result.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
387 @var{result} is a PGresult object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
388
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
389 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
390 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
391 @result{} #<PGresult PGRES_TUPLES_OK[5] - SELECT>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
392 (pq-nfields R)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
393 @result{} 3
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
394 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
395 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
396
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
397 @defun pq-binary-tuples result
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
398 Returns t if binary tuples are present in the results, nil otherwise.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
399 @var{result} is a PGresult object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
400
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
401 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
402 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
403 @result{} #<PGresult PGRES_TUPLES_OK[5] - SELECT>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
404 (pq-binary-tuples R)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
405 @result{} nil
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
406 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
407 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
408
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
409 @defun pq-fname result field-index
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
410 Returns the name of a specific field.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
411 @var{result} is a PGresult object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
412 @var{field-index} is the number of the column to select from. The first
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
413 column is number zero.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
414
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
415 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
416 (let (i l)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
417 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
418 (setq i (pq-nfields R))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
419 (while (>= (decf i) 0)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
420 (push (pq-fname R i) l))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
421 l)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
422 @result{} ("id" "shikona" "rank")
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
423 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
424 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
425
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
426 @defun pq-fnumber result field-name
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
427 Return the field number corresponding to the given field name.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
428 -1 is returned on a bad field name.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
429 @var{result} is a PGresult object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
430 @var{field-name} is a string representing the field name to find.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
431 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
432 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
433 @result{} #<PGresult PGRES_TUPLES_OK[5] - SELECT>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
434 (pq-fnumber R "id")
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
435 @result{} 0
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
436 (pq-fnumber R "Not a field")
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
437 @result{} -1
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
438 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
439 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
440
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
441 @defun pq-ftype result field-num
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
442 Return an integer code representing the data type of the specified column.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
443 @var{result} is a PGresult object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
444 @var{field-num} is the field number.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
445
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
446 The return value of this function is the Object ID (Oid) in the database
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
447 of the type. Further queries need to be made to various system tables
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
448 in order to convert this value into something useful.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
449 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
450
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
451 @defun pq-fmod result field-num
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
452 Return the type modifier code associated with a field. Field numbers
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
453 start at zero.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
454 @var{result} is a PGresult object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
455 @var{field-index} selects which field to use.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
456 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
457
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
458 @defun pq-fsize result field-index
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
459 Return size of the given field.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
460 @var{result} is a PGresult object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
461 @var{field-index} selects which field to use.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
462
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
463 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
464 (let (i l)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
465 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
466 (setq i (pq-nfields R))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
467 (while (>= (decf i) 0)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
468 (push (list (pq-ftype R i) (pq-fsize R i)) l))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
469 l)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
470 @result{} ((23 23) (25 25) (25 25))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
471 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
472 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
473
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
474 @defun pq-get-value result tup-num field-num
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
475 Retrieve a return value.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
476 @var{result} is a PGresult object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
477 @var{tup-num} selects which tuple to fetch from.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
478 @var{field-num} selects which field to fetch from.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
479
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
480 Both tuples and fields are numbered from zero.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
481
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
482 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
483 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
484 @result{} #<PGresult PGRES_TUPLES_OK[5] - SELECT>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
485 (pq-get-value R 0 1)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
486 @result{} "Musashimaru"
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
487 (pq-get-value R 1 1)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
488 @result{} "Dejima"
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
489 (pq-get-value R 2 1)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
490 @result{} "Musoyama"
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
491 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
492 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
493
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
494 @defun pq-get-length result tup-num field-num
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
495 Return the length of a specific value.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
496 @var{result} is a PGresult object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
497 @var{tup-num} selects which tuple to fetch from.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
498 @var{field-num} selects which field to fetch from.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
499
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
500 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
501 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
502 @result{} #<PGresult PGRES_TUPLES_OK[5] - SELECT>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
503 (pq-get-length R 0 1)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
504 @result{} 11
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
505 (pq-get-length R 1 1)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
506 @result{} 6
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
507 (pq-get-length R 2 1)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
508 @result{} 8
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
509 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
510 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
511
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
512 @defun pq-get-is-null result tup-num field-num
1738
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
513 Return t if the specific value is the SQL @code{NULL}.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
514 @var{result} is a PGresult object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
515 @var{tup-num} selects which tuple to fetch from.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
516 @var{field-num} selects which field to fetch from.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
517 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
518
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
519 @defun pq-cmd-status result
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
520 Return a summary string from the query.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
521 @var{result} is a PGresult object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
522 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
523 @comment This example was written on day 3 of the 2000 Haru Basho.
464
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 444
diff changeset
524 (setq R (pq-exec P "INSERT INTO xemacs_test
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 444
diff changeset
525 VALUES (6, 'Wakanohana', 'Yokozuna');"))
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
526 @result{} #<PGresult PGRES_COMMAND_OK[1] - INSERT 542086 1>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
527 (pq-cmd-status R)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
528 @result{} "INSERT 542086 1"
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
529 (setq R (pq-exec P "UPDATE xemacs_test SET rank='retired'
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
530 WHERE shikona='Wakanohana';"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
531 @result{} #<PGresult PGRES_COMMAND_OK[1] - UPDATE 1>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
532 (pq-cmd-status R)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
533 @result{} "UPDATE 1"
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
534 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
535
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
536 Note that the first number returned from an insertion, like in the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
537 example, is an object ID number and will almost certainly vary from
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
538 system to system since object ID numbers in Postgres must be unique
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
539 across all databases.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
540 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
541
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
542 @defun pq-cmd-tuples result
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
543 Return the number of tuples if the last command was an INSERT/UPDATE/DELETE.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
544 If the last command was something else, the empty string is returned.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
545 @var{result} is a PGresult object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
546
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
547 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
548 (setq R (pq-exec P "INSERT INTO xemacs_test VALUES
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
549 (7, 'Takanohana', 'Yokuzuna');"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
550 @result{} #<PGresult PGRES_COMMAND_OK[1] - INSERT 38688 1>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
551 (pq-cmd-tuples R)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
552 @result{} "1"
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
553 (setq R (pq-exec P "SELECT * from xemacs_test;"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
554 @result{} #<PGresult PGRES_TUPLES_OK[7] - SELECT>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
555 (pq-cmd-tuples R)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
556 @result{} ""
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
557 (setq R (pq-exec P "DELETE FROM xemacs_test
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
558 WHERE shikona LIKE '%hana';"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
559 @result{} #<PGresult PGRES_COMMAND_OK[2] - DELETE 2>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
560 (pq-cmd-tuples R)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
561 @result{} "2"
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
562 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
563 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
564
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
565 @defun pq-oid-value result
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
566 Return the object id of the insertion if the last command was an INSERT.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
567 0 is returned if the last command was not an insertion.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
568 @var{result} is a PGresult object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
569
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
570 In the first example, the numbers you will see on your local system will
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
571 almost certainly be different, however the second number from the right
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
572 in the unprintable PGresult object and the number returned by
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
573 @code{pq-oid-value} should match.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
574 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
575 (setq R (pq-exec P "INSERT INTO xemacs_test VALUES
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
576 (8, 'Terao', 'Maegashira');"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
577 @result{} #<PGresult PGRES_COMMAND_OK[1] - INSERT 542089 1>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
578 (pq-oid-value R)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
579 @result{} 542089
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
580 (setq R (pq-exec P "SELECT shikona FROM xemacs_test
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
581 WHERE rank='Maegashira';"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
582 @result{} #<PGresult PGRES_TUPLES_OK[2] - SELECT>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
583 (pq-oid-value R)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
584 @result{} 0
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
585 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
586 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
587
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
588 @defun pq-make-empty-pgresult conn status
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
589 Create an empty pgresult with the given status.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
590 @var{conn} a database connection object
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
591 @var{status} a value that can be returned by @code{pq-result-status}.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
592
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
593 The caller is responsible for making sure the return value gets properly
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
594 freed.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
595 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
596
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
597 @node Synchronous Interface Functions, Asynchronous Interface Functions, libpq Lisp Symbols and DataTypes, XEmacs PostgreSQL libpq API
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
598 @comment node-name, next, previous, up
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
599 @subsection Synchronous Interface Functions
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
600
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
601 @defun pq-connectdb conninfo
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
602 Establish a (synchronous) database connection.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
603 @var{conninfo} A string of blank separated options. Options are of the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
604 form ``@var{option} = @var{value}''. If @var{value} contains blanks, it
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
605 must be single quoted. Blanks around the equal sign are optional.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
606 Multiple option assignments are blank separated.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
607 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
608 (pq-connectdb "dbname=japanese port = 25432")
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
609 @result{} #<PGconn localhost:25432 steve/japanese>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
610 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
611 The printed representation of a database connection object has four
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
612 fields. The first field is the hostname where the database server is
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
613 running (in this case localhost), the second field is the port number,
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
614 the third field is the database user name, and the fourth field is the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
615 name of the database.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
616
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
617 Database connection objects which have been disconnected and will
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
618 generate an immediate error if they are used look like:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
619 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
620 #<PGconn BAD>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
621 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
622 Bad connections can be reestablished with @code{pq-reset}, or deleted
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
623 entirely with @code{pq-finish}.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
624
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
625 A database connection object that has been deleted looks like:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
626 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
627 (let ((P1 (pq-connectdb "")))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
628 (pq-finish P1)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
629 P1)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
630 @result{} #<PGconn DEAD>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
631 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
632
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
633 Note that database connection objects are the most heavy weight objects
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
634 in XEmacs Lisp at this writing, usually representing as much as several
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
635 megabytes of virtual memory on the machine the database server is
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
636 running on. It is wisest to explicitly delete them when you are
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
637 finished with them, rather than letting garbage collection do it. An
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
638 example idiom is:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
639
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
640 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
641 (let ((P (pq-connectiondb "")))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
642 (unwind-protect
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
643 (progn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
644 (...)) ; access database here
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
645 (pq-finish P)))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
646 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
647
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
648 The following options are available in the options string:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
649 @table @code
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
650 @item authtype
1738
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
651 Authentication type. Same as @code{PGAUTHTYPE}. This is no longer used.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
652 @item user
1738
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
653 Database user name. Same as @code{PGUSER}.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
654 @item password
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
655 Database password.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
656 @item dbname
1738
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
657 Database name. Same as @code{PGDATABASE}
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
658 @item host
1738
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
659 Symbolic hostname. Same as @code{PGHOST}.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
660 @item hostaddr
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
661 Host address as four octets (eg. like 192.168.1.1).
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
662 @item port
1738
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
663 TCP port to connect to. Same as @code{PGPORT}.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
664 @item tty
1738
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
665 Debugging TTY. Same as @code{PGTTY}. This value is suppressed in the
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
666 XEmacs Lisp API.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
667 @item options
1738
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
668 Extra backend database options. Same as @code{PGOPTIONS}.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
669 @end table
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
670 A database connection object is returned regardless of whether a
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
671 connection was established or not.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
672 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
673
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
674 @defun pq-reset conn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
675 Reestablish database connection.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
676 @var{conn} A database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
677
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
678 This function reestablishes a database connection using the original
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
679 connection parameters. This is useful if something has happened to the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
680 TCP link and it has become broken.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
681 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
682
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
683 @defun pq-exec conn query
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
684 Make a synchronous database query.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
685 @var{conn} A database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
686 @var{query} A string containing an SQL query.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
687 A PGresult object is returned, which in turn may be queried by its many
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
688 accessor functions to retrieve state out of it. If the query string
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
689 contains multiple SQL commands, only results from the final command are
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
690 returned.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
691
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
692 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
693 (setq R (pq-exec P "SELECT * FROM xemacs_test;
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
694 DELETE FROM xemacs_test WHERE id=8;"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
695 @result{} #<PGresult PGRES_COMMAND_OK[1] - DELETE 1>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
696 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
697 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
698
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
699 @defun pq-notifies conn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
700 Return the latest async notification that has not yet been handled.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
701 @var{conn} A database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
702 If there has been a notification, then a list of two elements will be returned.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
703 The first element contains the relation name being notified, the second
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
704 element contains the backend process ID number. nil is returned if there
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
705 aren't any notifications to process.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
706 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
707
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
708 @defun PQsetenv conn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
709 Synchronous transfer of environment variables to a backend
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
710 @var{conn} A database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
711
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
712 Environment variable transfer is done as a normal part of database
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
713 connection.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
714
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
715 Compatibility note: This function was present but not documented in versions
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
716 of libpq prior to 7.0.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
717 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
718
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
719 @node Asynchronous Interface Functions, Large Object Support, Synchronous Interface Functions, XEmacs PostgreSQL libpq API
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
720 @comment node-name, next, previous, up
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
721 @subsection Asynchronous Interface Functions
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
722
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
723 Making command by command examples is too complex with the asynchronous
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
724 interface functions. See the examples section for complete calling
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
725 sequences.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
726
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
727 @defun pq-connect-start conninfo
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
728 Begin establishing an asynchronous database connection.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
729 @var{conninfo} A string containing the connection options. See the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
730 documentation of @code{pq-connectdb} for a listing of all the available
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
731 flags.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
732 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
733
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
734 @defun pq-connect-poll conn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
735 An intermediate function to be called during an asynchronous database
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
736 connection.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
737 @var{conn} A database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
738 The result codes are documented in a previous section.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
739 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
740
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
741 @defun pq-is-busy conn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
742 Returns t if @code{pq-get-result} would block waiting for input.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
743 @var{conn} A database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
744 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
745
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
746 @defun pq-consume-input conn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
747 Consume any available input from the backend.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
748 @var{conn} A database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
749
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
750 Nil is returned if anything bad happens.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
751 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
752
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
753 @defun pq-reset-start conn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
754 Reset connection to the backend asynchronously.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
755 @var{conn} A database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
756 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
757
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
758 @defun pq-reset-poll conn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
759 Poll an asynchronous reset for completion
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
760 @var{conn} A database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
761 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
762
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
763 @defun pq-reset-cancel conn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
764 Attempt to request cancellation of the current operation.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
765 @var{conn} A database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
766
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
767 The return value is t if the cancel request was successfully
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
768 dispatched, nil if not (in which case conn->errorMessage is set).
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
769 Note: successful dispatch is no guarantee that there will be any effect at
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
770 the backend. The application must read the operation result as usual.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
771 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
772
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
773 @defun pq-send-query conn query
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
774 Submit a query to Postgres and don't wait for the result.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
775 @var{conn} A database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
776 Returns: t if successfully submitted
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
777 nil if error (conn->errorMessage is set)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
778 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
779
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
780 @defun pq-get-result conn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
781 Retrieve an asynchronous result from a query.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
782 @var{conn} A database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
783
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
784 @code{nil} is returned when no more query work remains.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
785 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
786
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
787 @defun pq-set-nonblocking conn arg
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
788 Sets the PGconn's database connection non-blocking if the arg is TRUE
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
789 or makes it non-blocking if the arg is FALSE, this will not protect
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
790 you from PQexec(), you'll only be safe when using the non-blocking API.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
791 @var{conn} A database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
792 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
793
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
794 @defun pq-is-nonblocking conn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
795 Return the blocking status of the database connection
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
796 @var{conn} A database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
797 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
798
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
799 @defun pq-flush conn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
800 Force the write buffer to be written (or at least try)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
801 @var{conn} A database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
802 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
803
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
804 @defun PQsetenvStart conn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
805 Start asynchronously passing environment variables to a backend.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
806 @var{conn} A database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
807
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
808 Compatibility note: this function is only available with libpq-7.0.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
809 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
810
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
811 @defun PQsetenvPoll conn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
812 Check an asynchronous environment variables transfer for completion.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
813 @var{conn} A database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
814
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
815 Compatibility note: this function is only available with libpq-7.0.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
816 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
817
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
818 @defun PQsetenvAbort conn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
819 Attempt to terminate an asynchronous environment variables transfer.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
820 @var{conn} A database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
821
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
822 Compatibility note: this function is only available with libpq-7.0.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
823 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
824
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
825 @node Large Object Support, Other libpq Functions, Asynchronous Interface Functions, XEmacs PostgreSQL libpq API
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
826 @comment node-name, next, previous, up
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
827 @subsection Large Object Support
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
828
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
829 @defun pq-lo-import conn filename
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
830 Import a file as a large object into the database.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
831 @var{conn} a database connection object
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
832 @var{filename} filename to import
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
833
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
834 On success, the object id is returned.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
835 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
836
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
837 @defun pq-lo-export conn oid filename
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
838 Copy a large object in the database into a file.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
839 @var{conn} a database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
840 @var{oid} object id number of a large object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
841 @var{filename} filename to export to.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
842 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
843
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
844 @node Other libpq Functions, Unimplemented libpq Functions, Large Object Support, XEmacs PostgreSQL libpq API
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
845 @comment node-name, next, previous, up
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
846 @subsection Other libpq Functions
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
847
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
848 @defun pq-finish conn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
849 Destroy a database connection object by calling free on it.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
850 @var{conn} a database connection object
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
851
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
852 It is possible to not call this routine because the usual XEmacs garbage
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
853 collection mechanism will call the underlying libpq routine whenever it
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
854 is releasing stale @code{PGconn} objects. However, this routine is
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
855 useful in @code{unwind-protect} clauses to make connections go away
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
856 quickly when unrecoverable errors have occurred.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
857
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
858 After calling this routine, the printed representation of the XEmacs
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
859 wrapper object will contain the string ``DEAD''.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
860 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
861
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
862 @defun pq-client-encoding conn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
863 Return the client encoding as an integer code.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
864 @var{conn} a database connection object
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
865
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
866 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
867 (pq-client-encoding P)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
868 @result{} 1
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
869 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
870
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
871 Compatibility note: This function did not exist prior to libpq-7.0 and
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
872 does not exist in a non-Mule XEmacs.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
873 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
874
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
875 @defun pq-set-client-encoding conn encoding
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
876 Set client coding system.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
877 @var{conn} a database connection object
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
878 @var{encoding} a string representing the desired coding system
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
879
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
880 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
881 (pq-set-client-encoding P "EUC_JP")
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
882 @result{} 0
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
883 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
884
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
885 The current idiom for ensuring proper coding system conversion is the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
886 following (illustrated for EUC Japanese encoding):
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
887 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
888 (setq P (pq-connectdb "..."))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
889 (let ((file-name-coding-system 'euc-jp)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
890 (pg-coding-system 'euc-jp))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
891 (pq-set-client-encoding "EUC_JP")
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
892 ...)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
893 (pq-finish P)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
894 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
895 Compatibility note: This function did not exist prior to libpq-7.0 and
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
896 does not exist in a non-Mule XEmacs.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
897 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
898
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
899 @defun pq-env-2-encoding
1738
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
900 Return the integer code representing the coding system in
f43f9ca6c7d9 [xemacs-hg @ 2003-10-10 12:39:27 by stephent]
stephent
parents: 464
diff changeset
901 @code{PGCLIENTENCODING}.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
902
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
903 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
904 (pq-env-2-encoding)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
905 @result{} 0
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
906 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
907 Compatibility note: This function did not exist prior to libpq-7.0 and
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
908 does not exist in a non-Mule XEmacs.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
909 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
910
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
911 @defun pq-clear res
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
912 Destroy a query result object by calling free() on it.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
913 @var{res} a query result object
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
914
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
915 Note: The memory allocation systems of libpq and XEmacs are different.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
916 The XEmacs representation of a query result object will have both the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
917 XEmacs version and the libpq version freed at the next garbage collection
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
918 when the object is no longer being referenced. Calling this function does
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
919 not release the XEmacs object, it is still subject to the usual rules for
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
920 Lisp objects. The printed representation of the XEmacs object will contain
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
921 the string ``DEAD'' after this routine is called indicating that it is no
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
922 longer useful for anything.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
923 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
924
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
925 @defun pq-conn-defaults
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
926 Return a data structure that represents the connection defaults.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
927 The data is returned as a list of lists, where each sublist contains
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
928 info regarding a single option.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
929 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
930
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
931 @node Unimplemented libpq Functions, , Other libpq Functions, XEmacs PostgreSQL libpq API
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
932 @comment node-name, next, previous, up
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
933 @subsection Unimplemented libpq Functions
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
934
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
935 @deftypefn {Unimplemented Function} PGconn *PQsetdbLogin (char *pghost, char *pgport, char *pgoptions, char *pgtty, char *dbName, char *login, char *pwd)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
936 Synchronous database connection.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
937 @var{pghost} is the hostname of the PostgreSQL backend to connect to.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
938 @var{pgport} is the TCP port number to use.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
939 @var{pgoptions} specifies other backend options.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
940 @var{pgtty} specifies the debugging tty to use.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
941 @var{dbName} specifies the database name to use.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
942 @var{login} specifies the database user name.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
943 @var{pwd} specifies the database user's password.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
944
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
945 This routine is deprecated as of libpq-7.0, and its functionality can be
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
946 replaced by external Lisp code if needed.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
947 @end deftypefn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
948
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
949 @deftypefn {Unimplemented Function} PGconn *PQsetdb (char *pghost, char *pgport, char *pgoptions, char *pgtty, char *dbName)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
950 Synchronous database connection.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
951 @var{pghost} is the hostname of the PostgreSQL backend to connect to.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
952 @var{pgport} is the TCP port number to use.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
953 @var{pgoptions} specifies other backend options.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
954 @var{pgtty} specifies the debugging tty to use.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
955 @var{dbName} specifies the database name to use.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
956
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
957 This routine was deprecated in libpq-6.5.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
958 @end deftypefn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
959
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
960 @deftypefn {Unimplemented Function} int PQsocket (PGconn *conn)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
961 Return socket file descriptor to a backend database process.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
962 @var{conn} database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
963 @end deftypefn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
964
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
965 @deftypefn {Unimplemented Function} void PQprint (FILE *fout, PGresult *res, PGprintOpt *ps)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
966 Print out the results of a query to a designated C stream.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
967 @var{fout} C stream to print to
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
968 @var{res} the query result object to print
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
969 @var{ps} the print options structure.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
970
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
971 This routine is deprecated as of libpq-7.0 and cannot be sensibly exported
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
972 to XEmacs Lisp.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
973 @end deftypefn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
974
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
975 @deftypefn {Unimplemented Function} void PQdisplayTuples (PGresult *res, FILE *fp, int fillAlign, char *fieldSep, int printHeader, int quiet)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
976 @var{res} query result object to print
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
977 @var{fp} C stream to print to
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
978 @var{fillAlign} pad the fields with spaces
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
979 @var{fieldSep} field separator
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
980 @var{printHeader} display headers?
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
981 @var{quiet}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
982
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
983 This routine was deprecated in libpq-6.5.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
984 @end deftypefn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
985
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
986 @deftypefn {Unimplemented Function} void PQprintTuples (PGresult *res, FILE *fout, int printAttName, int terseOutput, int width)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
987 @var{res} query result object to print
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
988 @var{fout} C stream to print to
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
989 @var{printAttName} print attribute names
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
990 @var{terseOutput} delimiter bars
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
991 @var{width} width of column, if 0, use variable width
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
992
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
993 This routine was deprecated in libpq-6.5.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
994 @end deftypefn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
995
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
996 @deftypefn {Unimplemented Function} int PQmblen (char *s, int encoding)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
997 Determine length of a multibyte encoded char at @code{*s}.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
998 @var{s} encoded string
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
999 @var{encoding} type of encoding
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1000
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1001 Compatibility note: This function was introduced in libpq-7.0.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1002 @end deftypefn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1003
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1004 @deftypefn {Unimplemented Function} void PQtrace (PGconn *conn, FILE *debug_port)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1005 Enable tracing on @code{debug_port}.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1006 @var{conn} database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1007 @var{debug_port} C output stream to use.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1008 @end deftypefn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1009
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1010 @deftypefn {Unimplemented Function} void PQuntrace (PGconn *conn)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1011 Disable tracing.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1012 @var{conn} database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1013 @end deftypefn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1014
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1015 @deftypefn {Unimplemented Function} char *PQoidStatus (PGconn *conn)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1016 Return the object id as a string of the last tuple inserted.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1017 @var{conn} database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1018
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1019 Compatibility note: This function is deprecated in libpq-7.0, however it
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1020 is used internally by the XEmacs binding code when linked against versions
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1021 prior to 7.0.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1022 @end deftypefn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1023
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1024 @deftypefn {Unimplemented Function} PGresult *PQfn (PGconn *conn, int fnid, int *result_buf, int *result_len, int result_is_int, PQArgBlock *args, int nargs)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1025 ``Fast path'' interface --- not really recommended for application use
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1026 @var{conn} A database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1027 @var{fnid}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1028 @var{result_buf}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1029 @var{result_len}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1030 @var{result_is_int}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1031 @var{args}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1032 @var{nargs}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1033 @end deftypefn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1034
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1035 The following set of very low level large object functions aren't
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1036 appropriate to be exported to Lisp.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1037
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1038 @deftypefn {Unimplemented Function} int pq-lo-open (PGconn *conn, int lobjid, int mode)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1039 @var{conn} a database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1040 @var{lobjid} a large object ID.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1041 @var{mode} opening modes.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1042 @end deftypefn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1043
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1044 @deftypefn {Unimplemented Function} int pq-lo-close (PGconn *conn, int fd)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1045 @var{conn} a database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1046 @var{fd} a large object file descriptor
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1047 @end deftypefn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1048
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1049 @deftypefn {Unimplemented Function} int pq-lo-read (PGconn *conn, int fd, char *buf, int len)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1050 @var{conn} a database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1051 @var{fd} a large object file descriptor.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1052 @var{buf} buffer to read into.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1053 @var{len} size of buffer.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1054 @end deftypefn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1055
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1056 @deftypefn {Unimplemented Function} int pq-lo-write (PGconn *conn, int fd, char *buf, size_t len)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1057 @var{conn} a database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1058 @var{fd} a large object file descriptor.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1059 @var{buf} buffer to write from.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1060 @var{len} size of buffer.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1061 @end deftypefn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1062
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1063 @deftypefn {Unimplemented Function} int pq-lo-lseek (PGconn *conn, int fd, int offset, int whence)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1064 @var{conn} a database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1065 @var{fd} a large object file descriptor.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1066 @var{offset}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1067 @var{whence}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1068 @end deftypefn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1069
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1070 @deftypefn {Unimplemented Function} int pq-lo-creat (PGconn *conn, int mode)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1071 @var{conn} a database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1072 @var{mode} opening modes.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1073 @end deftypefn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1074
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1075 @deftypefn {Unimplemented Function} int pq-lo-tell (PGconn *conn, int fd)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1076 @var{conn} a database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1077 @var{fd} a large object file descriptor.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1078 @end deftypefn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1079
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1080 @deftypefn {Unimplemented Function} int pq-lo-unlink (PGconn *conn, int lobjid)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1081 @var{conn} a database connection object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1082 @var{lbojid} a large object ID.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1083 @end deftypefn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1084
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1085 @node XEmacs PostgreSQL libpq Examples, , XEmacs PostgreSQL libpq API, PostgreSQL Support
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1086 @comment node-name, next, previous, up
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1087 @section XEmacs PostgreSQL libpq Examples
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1088
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1089 This is an example of one method of establishing an asynchronous
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1090 connection.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1091
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1092 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1093 (defun database-poller (P)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1094 (message "%S before poll" (pq-pgconn P 'pq::status))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1095 (pq-connect-poll P)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1096 (message "%S after poll" (pq-pgconn P 'pq::status))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1097 (if (eq (pq-pgconn P 'pq::status) 'pg::connection-ok)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1098 (message "Done!")
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1099 (add-timeout .1 'database-poller P)))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1100 @result{} database-poller
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1101 (progn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1102 (setq P (pq-connect-start ""))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1103 (add-timeout .1 'database-poller P))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1104 @result{} pg::connection-started before poll
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1105 @result{} pg::connection-made after poll
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1106 @result{} pg::connection-made before poll
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1107 @result{} pg::connection-awaiting-response after poll
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1108 @result{} pg::connection-awaiting-response before poll
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1109 @result{} pg::connection-auth-ok after poll
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1110 @result{} pg::connection-auth-ok before poll
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1111 @result{} pg::connection-setenv after poll
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1112 @result{} pg::connection-setenv before poll
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1113 @result{} pg::connection-ok after poll
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1114 @result{} Done!
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1115 P
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1116 @result{} #<PGconn localhost:25432 steve/steve>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1117 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1118
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1119 Here is an example of one method of doing an asynchronous reset.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1120
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1121 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1122 (defun database-poller (P)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1123 (let (PS)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1124 (message "%S before poll" (pq-pgconn P 'pq::status))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1125 (setq PS (pq-reset-poll P))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1126 (message "%S after poll [%S]" (pq-pgconn P 'pq::status) PS)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1127 (if (eq (pq-pgconn P 'pq::status) 'pg::connection-ok)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1128 (message "Done!")
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1129 (add-timeout .1 'database-poller P))))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1130 @result{} database-poller
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1131 (progn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1132 (pq-reset-start P)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1133 (add-timeout .1 'database-poller P))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1134 @result{} pg::connection-started before poll
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1135 @result{} pg::connection-made after poll [pgres::polling-writing]
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1136 @result{} pg::connection-made before poll
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1137 @result{} pg::connection-awaiting-response after poll [pgres::polling-reading]
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1138 @result{} pg::connection-awaiting-response before poll
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1139 @result{} pg::connection-setenv after poll [pgres::polling-reading]
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1140 @result{} pg::connection-setenv before poll
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1141 @result{} pg::connection-ok after poll [pgres::polling-ok]
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1142 @result{} Done!
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1143 P
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1144 @result{} #<PGconn localhost:25432 steve/steve>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1145 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1146
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1147 And finally, an asynchronous query.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1148
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1149 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1150 (defun database-poller (P)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1151 (let (R)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1152 (pq-consume-input P)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1153 (if (pq-is-busy P)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1154 (add-timeout .1 'database-poller P)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1155 (setq R (pq-get-result P))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1156 (if R
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1157 (progn
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1158 (push R result-list)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1159 (add-timeout .1 'database-poller P))))))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1160 @result{} database-poller
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1161 (when (pq-send-query P "SELECT * FROM xemacs_test;")
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1162 (setq result-list nil)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1163 (add-timeout .1 'database-poller P))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1164 @result{} 885
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1165 ;; wait a moment
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1166 result-list
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1167 @result{} (#<PGresult PGRES_TUPLES_OK - SELECT>)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1168 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1169
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1170 Here is an example showing how multiple SQL statements in a single query
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1171 can have all their results collected.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1172 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1173 ;; Using the same @code{database-poller} function from the previous example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1174 (when (pq-send-query P "SELECT * FROM xemacs_test;
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1175 SELECT * FROM pg_database;
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1176 SELECT * FROM pg_user;")
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1177 (setq result-list nil)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1178 (add-timeout .1 'database-poller P))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1179 @result{} 1782
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1180 ;; wait a moment
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1181 result-list
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1182 @result{} (#<PGresult PGRES_TUPLES_OK - SELECT> #<PGresult PGRES_TUPLES_OK - SELECT> #<PGresult PGRES_TUPLES_OK - SELECT>)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1183 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1184
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1185 Here is an example which illustrates collecting all data from a query,
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1186 including the field names.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1187
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1188 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1189 (defun pg-util-query-results (results)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1190 "Retrieve results of last SQL query into a list structure."
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1191 (let ((i (1- (pq-ntuples R)))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1192 j l1 l2)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1193 (while (>= i 0)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1194 (setq j (1- (pq-nfields R)))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1195 (setq l2 nil)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1196 (while (>= j 0)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1197 (push (pq-get-value R i j) l2)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1198 (decf j))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1199 (push l2 l1)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1200 (decf i))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1201 (setq j (1- (pq-nfields R)))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1202 (setq l2 nil)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1203 (while (>= j 0)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1204 (push (pq-fname R j) l2)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1205 (decf j))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1206 (push l2 l1)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1207 l1))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1208 @result{} pg-util-query-results
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1209 (setq R (pq-exec P "SELECT * FROM xemacs_test ORDER BY field2 DESC;"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1210 @result{} #<PGresult PGRES_TUPLES_OK - SELECT>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1211 (pg-util-query-results R)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1212 @result{} (("f1" "field2") ("a" "97") ("b" "97") ("stuff" "42") ("a string" "12") ("foo" "10") ("string" "2") ("text" "1"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1213 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1214
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1215 Here is an example of a query that uses a database cursor.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1216
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1217 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1218 (let (data R)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1219 (setq R (pq-exec P "BEGIN;"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1220 (setq R (pq-exec P "DECLARE k_cursor CURSOR FOR SELECT * FROM xemacs_test ORDER BY f1 DESC;"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1221
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1222 (setq R (pq-exec P "FETCH k_cursor;"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1223 (while (eq (pq-ntuples R) 1)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1224 (push (list (pq-get-value R 0 0) (pq-get-value R 0 1)) data)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1225 (setq R (pq-exec P "FETCH k_cursor;")))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1226 (setq R (pq-exec P "END;"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1227 data)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1228 @result{} (("a" "97") ("a string" "12") ("b" "97") ("foo" "10") ("string" "2") ("stuff" "42") ("text" "1"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1229 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1230
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1231 Here's another example of cursors, this time with a Lisp macro to
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1232 implement a mapping function over a table.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1233
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1234 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1235 (defmacro map-db (P table condition callout)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1236 `(let (R)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1237 (pq-exec ,P "BEGIN;")
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1238 (pq-exec ,P (concat "DECLARE k_cursor CURSOR FOR SELECT * FROM "
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1239 ,table
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1240 " "
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1241 ,condition
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1242 " ORDER BY f1 DESC;"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1243 (setq R (pq-exec P "FETCH k_cursor;"))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1244 (while (eq (pq-ntuples R) 1)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1245 (,callout (pq-get-value R 0 0) (pq-get-value R 0 1))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1246 (setq R (pq-exec P "FETCH k_cursor;")))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1247 (pq-exec P "END;")))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1248 @result{} map-db
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1249 (defun callback (arg1 arg2)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1250 (message "arg1 = %s, arg2 = %s" arg1 arg2))
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1251 @result{} callback
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1252 (map-db P "xemacs_test" "WHERE field2 > 10" callback)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1253 @result{} arg1 = stuff, arg2 = 42
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1254 @result{} arg1 = b, arg2 = 97
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1255 @result{} arg1 = a string, arg2 = 12
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1256 @result{} arg1 = a, arg2 = 97
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1257 @result{} #<PGresult PGRES_COMMAND_OK - COMMIT>
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents:
diff changeset
1258 @end example