1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: LDAP Variables, Next: The High-Level LDAP API, Prev: XEmacs LDAP API, Up: XEmacs LDAP API
58 - Variable: ldap-default-host
59 The default LDAP server hostname. A TCP port number can be
60 appended to that name using a colon as a separator.
62 - Variable: ldap-default-port
63 Default TCP port for LDAP connections. Initialized from the LDAP
64 library. Default value is 389.
66 - Variable: ldap-default-base
67 Default base for LDAP searches. This is a string using the syntax
68 of RFC 1779. For instance, "o=ACME, c=US" limits the search to the
69 Acme organization in the United States.
71 - Variable: ldap-host-parameters-alist
72 An alist of per host options for LDAP transactions. The list
73 elements look like `(HOST PROP1 VAL1 PROP2 VAL2 ...)' HOST is the
74 name of an LDAP server. A TCP port number can be appended to that
75 name using a colon as a separator. PROPN and VALN are
76 property/value pairs describing parameters for the server. Valid
79 The distinguished name of the user to bind as. This may look
80 like `cn=Babs Jensen,o=ACME,c=US', see RFC 1779 for details.
83 The password to use for authentication.
86 The authentication method to use, possible values depend on
87 the LDAP library XEmacs was compiled with, they may include
88 `simple', `krbv41' and `krbv42'.
91 The base for the search. This may look like `cÿ, o¬me', see
92 RFC 1779 for syntax details.
95 One of the symbols `base', `onelevel' or `subtree' indicating
96 the scope of the search limited to a base object, to a single
97 level or to the whole subtree.
100 The dereference policy is one of the symbols `never',
101 `always', `search' or `find' and defines how aliases are
104 Aliases are never dereferenced
107 Aliases are always dereferenced
110 Aliases are dereferenced when searching
113 Aliases are dereferenced when locating the base object
117 The timeout limit for the connection in seconds.
120 The maximum number of matches to return for searches
121 performed on this connection.
123 - Variable: ldap-verbose
124 If non-`nil', LDAP operations will echo progress messages.
128 File: lispref.info, Node: The High-Level LDAP API, Next: The Low-Level LDAP API, Prev: LDAP Variables, Up: XEmacs LDAP API
130 The High-Level LDAP API
131 -----------------------
133 The following functions provide the most convenient interface to
134 perform LDAP operations. All of them open a connection to a host,
135 perform an operation (add/search/modify/delete) on one or several
136 entries and cleanly close the connection thus insulating the user from
137 all the details of the low-level interface such as LDAP Lisp objects
138 *note The Low-Level LDAP API::.
140 Note that `ldap-search' which used to be the name of the high-level
141 search function in XEmacs 21.1 is now obsolete. For consistency in the
142 naming as well as backward compatibility, that function now acts as a
143 wrapper that calls either `ldap-search-basic' (low-level search
144 function) or `ldap-search-entries' (high-level search function)
145 according to the actual parameters. A direct call to one of these two
146 functions is preferred since it is faster and unambiguous.
148 - Function: ldap-search-entries filter &optional host attributes
150 Perform an LDAP search. FILTER is the search filter *note Syntax
151 of Search Filters:: HOST is the LDAP host on which to perform the
152 search. ATTRIBUTES is the specific attributes to retrieve, `nil'
153 means retrieve all. ATTRSONLY if non-`nil' retrieves the
154 attributes only without their associated values. If WITHDN is
155 non-`nil' each entry in the result will be prepended with its
156 distinguished name DN. Additional search parameters can be
157 specified through `ldap-host-parameters-alist'. The function
158 returns a list of matching entries. Each entry is itself an alist
159 of attribute/value pairs optionally preceded by the DN of the
160 entry according to the value of WITHDN.
162 - Function: ldap-add-entries entries &optional host binddn passwd
163 Add entries to an LDAP directory. ENTRIES is a list of entry
164 specifications of the form `(DN (ATTR . VALUE) (ATTR . VALUE) ...)'
165 where DN the distinguished name of an entry to add, the following
166 are cons cells containing attribute/value string pairs. HOST is
167 the LDAP host, defaulting to `ldap-default-host' BINDDN is the DN
168 to bind as to the server PASSWD is the corresponding password.
170 - Function: ldap-modify-entries entry-mods &optional host binddn passwd
171 Modify entries of an LDAP directory. ENTRY_MODS is a list of
172 entry modifications of the form `(DN MOD-SPEC1 MOD-SPEC2 ...)'
173 where DN is the distinguished name of the entry to modify, the
174 following are modification specifications. A modification
175 specification is itself a list of the form `(MOD-OP ATTR VALUE1
176 VALUE2 ...)' MOD-OP and ATTR are mandatory, VALUES are optional
177 depending on MOD-OP. MOD-OP is the type of modification, one of
178 the symbols `add', `delete' or `replace'. ATTR is the LDAP
179 attribute type to modify. HOST is the LDAP host, defaulting to
180 `ldap-default-host' BINDDN is the DN to bind as to the server
181 PASSWD is the corresponding password"
183 - Function: ldap-delete-entries dn &optional host binddn passwd
184 Delete an entry from an LDAP directory. DN is the distinguished
185 name of an entry to delete or a list of those. HOST is the LDAP
186 host, defaulting to `ldap-default-host' BINDDN is the DN to bind
187 as to the server PASSWD is the corresponding password.
190 File: lispref.info, Node: The Low-Level LDAP API, Next: LDAP Internationalization, Prev: The High-Level LDAP API, Up: XEmacs LDAP API
192 The Low-Level LDAP API
193 ----------------------
195 The low-level API should be used directly for very specific purposes
196 (such as multiple operations on a connection) only. The higher-level
197 functions provide a more convenient way to access LDAP directories
198 hiding the subtleties of handling the connection, translating arguments
199 and ensuring compliance with LDAP internationalization rules and formats
200 (currently partly implemented only). See *note The High-Level LDAP API::
202 Note that the former functions `ldap-*-internal' functions have been
203 renamed in XEmacs 21.2
207 * The LDAP Lisp Object::
208 * Opening and Closing a LDAP Connection::
209 * Low-level Operations on a LDAP Server::
212 File: lispref.info, Node: The LDAP Lisp Object, Next: Opening and Closing a LDAP Connection, Prev: The Low-Level LDAP API, Up: The Low-Level LDAP API
217 An internal built-in `ldap' lisp object represents a LDAP connection.
219 - Function: ldapp object
220 This function returns non-`nil' if OBJECT is a `ldap' object.
222 - Function: ldap-host ldap
223 Return the server host of the connection represented by LDAP
225 - Function: ldap-live-p ldap
226 Return non-`nil' if LDAP is an active LDAP connection
229 File: lispref.info, Node: Opening and Closing a LDAP Connection, Next: Low-level Operations on a LDAP Server, Prev: The LDAP Lisp Object, Up: The Low-Level LDAP API
231 Opening and Closing a LDAP Connection
232 .....................................
234 - Function: ldap-open host &optional plist
235 Open a LDAP connection to HOST. PLIST is a property list
236 containing additional parameters for the connection. Valid keys
239 The TCP port to use for the connection if different from
240 `ldap-default-port' or the library builtin value
243 The authentication method to use, possible values depend on
244 the LDAP library XEmacs was compiled with, they may include
245 `simple', `krbv41' and `krbv42'.
248 The distinguished name of the user to bind as. This may look
249 like `c=com, o=Acme, cn=Babs Jensen', see RFC 1779 for
253 The password to use for authentication.
256 The dereference policy is one of the symbols `never',
257 `always', `search' or `find' and defines how aliases are
260 Aliases are never dereferenced
263 Aliases are always dereferenced
266 Aliases are dereferenced when searching
269 Aliases are dereferenced when locating the base object
270 for the search The default is `never'.
273 The timeout limit for the connection in seconds.
276 The maximum number of matches to return for searches
277 performed on this connection.
279 - Function: ldap-close ldap
280 Close the connection represented by LDAP
283 File: lispref.info, Node: Low-level Operations on a LDAP Server, Prev: Opening and Closing a LDAP Connection, Up: The Low-Level LDAP API
285 Low-level Operations on a LDAP Server
286 .....................................
288 `ldap-search-basic' is the low-level primitive to perform a search
289 on a LDAP server. It works directly on an open LDAP connection thus
290 requiring a preliminary call to `ldap-open'. Multiple searches can be
291 made on the same connection, then the session must be closed with
294 - Function: ldap-search-basic ldap filter base scope attrs attrsonly
295 Perform a search on an open connection LDAP created with
296 `ldap-open'. FILTER is a filter string for the search *note
297 Syntax of Search Filters:: BASE is the distinguished name at which
298 to start the search. SCOPE is one of the symbols `base',
299 `onelevel' or `subtree' indicating the scope of the search limited
300 to a base object, to a single level or to the whole subtree. The
301 default is `subtree'. `attrs' is a list of strings indicating
302 which attributes to retrieve for each matching entry. If `nil' all
303 available attributes are returned. If `attrsonly' is non-`nil'
304 then only the attributes are retrieved, not their associated values
305 If `withdn' is non-`nil' then each entry in the result is
306 prepended with its distinguished name DN If `verbose' is non-`nil'
307 then progress messages are echoed The function returns a list of
308 matching entries. Each entry is itself an alist of
309 attribute/value pairs optionally preceded by the DN of the entry
310 according to the value of `withdn'.
312 - Function: ldap-add ldap dn entry
313 Add ENTRY to a LDAP directory which a connection LDAP has been
314 opened to with `ldap-open'. DN is the distinguished name of the
315 entry to add. ENTRY is an entry specification, i.e., a list of
316 cons cells containing attribute/value string pairs.
318 - Function: ldap-modify ldap dn mods
319 Modify an entry in an LDAP directory. LDAP is an LDAP connection
320 object created with `ldap-open'. DN is the distinguished name of
321 the entry to modify. MODS is a list of modifications to apply. A
322 modification is a list of the form `(MOD-OP ATTR VALUE1 VALUE2
323 ...)' MOD-OP and ATTR are mandatory, VALUES are optional
324 depending on MOD-OP. MOD-OP is the type of modification, one of
325 the symbols `add', `delete' or `replace'. ATTR is the LDAP
326 attribute type to modify
328 - Function: ldap-delete ldap dn
329 Delete an entry to an LDAP directory. LDAP is an LDAP connection
330 object created with `ldap-open'. DN is the distinguished name of
334 File: lispref.info, Node: LDAP Internationalization, Prev: The Low-Level LDAP API, Up: XEmacs LDAP API
336 LDAP Internationalization
337 -------------------------
339 The XEmacs LDAP API provides basic internationalization features
340 based on the LDAP v3 specification (essentially RFC2252 on "LDAP v3
341 Attribute Syntax Definitions"). Unfortunately since there is currently
342 no free LDAP v3 server software, this part has not received much
343 testing and should be considered experimental. The framework is in
346 - Function: ldap-decode-attribute attr
347 Decode the attribute/value pair ATTR according to LDAP rules. The
348 attribute name is looked up in `ldap-attribute-syntaxes-alist' and
349 the corresponding decoder is then retrieved from
350 `ldap-attribute-syntax-decoders'' and applied on the value(s).
354 * LDAP Internationalization Variables::
355 * Encoder/Decoder Functions::
358 File: lispref.info, Node: LDAP Internationalization Variables, Next: Encoder/Decoder Functions, Prev: LDAP Internationalization, Up: LDAP Internationalization
360 LDAP Internationalization Variables
361 ...................................
363 - Variable: ldap-ignore-attribute-codings
364 If non-`nil', no encoding/decoding will be performed LDAP
367 - Variable: ldap-coding-system
368 Coding system of LDAP string values. LDAP v3 specifies the coding
369 system of strings to be UTF-8. You need an XEmacs with Mule
372 - Variable: ldap-default-attribute-decoder
373 Decoder function to use for attributes whose syntax is unknown.
374 Such a function receives an encoded attribute value as a string
375 and should return the decoded value as a string
377 - Variable: ldap-attribute-syntax-encoders
378 A vector of functions used to encode LDAP attribute values. The
379 sequence of functions corresponds to the sequence of LDAP
380 attribute syntax object identifiers of the form
381 1.3.6.1.4.1.1466.1115.121.1.* as defined in RFC2252 section 4.3.2.
382 As of this writing, only a few encoder functions are available.
384 - Variable: ldap-attribute-syntax-decoders
385 A vector of functions used to decode LDAP attribute values. The
386 sequence of functions corresponds to the sequence of LDAP
387 attribute syntax object identifiers of the form
388 1.3.6.1.4.1.1466.1115.121.1.* as defined in RFC2252 section 4.3.2.
389 As of this writing, only a few decoder functions are available.
391 - Variable: ldap-attribute-syntaxes-alist
392 A map of LDAP attribute names to their type object id minor number.
393 This table is built from RFC2252 Section 5 and RFC2256 Section 5
396 File: lispref.info, Node: Encoder/Decoder Functions, Prev: LDAP Internationalization Variables, Up: LDAP Internationalization
398 Encoder/Decoder Functions
399 .........................
401 - Function: ldap-encode-boolean bool
402 A function that encodes an elisp boolean BOOL into a LDAP boolean
403 string representation
405 - Function: ldap-decode-boolean str
406 A function that decodes a LDAP boolean string representation STR
407 into an elisp boolean
409 - Function: ldap-decode-string str
410 Decode a string STR according to `ldap-coding-system'
412 - Function: ldap-encode-string str
413 Encode a string STR according to `ldap-coding-system'
415 - Function: ldap-decode-address str
416 Decode an address STR according to `ldap-coding-system' and
417 replacing $ signs with newlines as specified by LDAP encoding
420 - Function: ldap-encode-address str
421 Encode an address STR according to `ldap-coding-system' and
422 replacing newlines with $ signs as specified by LDAP encoding
426 File: lispref.info, Node: Syntax of Search Filters, Prev: XEmacs LDAP API, Up: LDAP Support
428 Syntax of Search Filters
429 ========================
431 LDAP search functions use RFC1558 syntax to describe the search
432 filter. In that syntax simple filters have the form:
434 (<attr> <filtertype> <value>)
436 `<attr>' is an attribute name such as `cn' for Common Name, `o' for
439 `<value>' is the corresponding value. This is generally an exact
440 string but may also contain `*' characters as wildcards
442 `filtertype' is one `=' `~=', `<=', `>=' which respectively describe
443 equality, approximate equality, inferiority and superiority.
445 Thus `(cn=John Smith)' matches all records having a canonical name
448 A special case is the presence filter `(<attr>=*' which matches
449 records containing a particular attribute. For instance `(mail=*)'
450 matches all records containing a `mail' attribute.
452 Simple filters can be connected together with the logical operators
453 `&', `|' and `!' which stand for the usual and, or and not operators.
455 `(&(objectClass=Person)(mail=*)(|(sn=Smith)(givenname=John)))'
456 matches records of class `Person' containing a `mail' attribute and
457 corresponding to people whose last name is `Smith' or whose first name
461 File: lispref.info, Node: PostgreSQL Support, Next: Internationalization, Prev: LDAP Support, Up: Top
466 XEmacs can be linked with PostgreSQL libpq run-time support to
467 provide relational database access from Emacs Lisp code.
471 * Building XEmacs with PostgreSQL support::
472 * XEmacs PostgreSQL libpq API::
473 * XEmacs PostgreSQL libpq Examples::
476 File: lispref.info, Node: Building XEmacs with PostgreSQL support, Next: XEmacs PostgreSQL libpq API, Up: PostgreSQL Support
478 Building XEmacs with PostgreSQL support
479 =======================================
481 XEmacs PostgreSQL support requires linking to the PostgreSQL libpq
482 library. Describing how to build and install PostgreSQL is beyond the
483 scope of this document. See the PostgreSQL manual for details.
485 If you have installed XEmacs from one of the binary kits on
486 (<ftp://ftp.xemacs.org/>), or are using an XEmacs binary from a CD ROM,
487 you may have XEmacs PostgreSQL support by default. `M-x
488 describe-installation' will tell you if you do.
490 If you are building XEmacs from source, you need to install
491 PostgreSQL first. On some systems, PostgreSQL will come pre-installed
492 in /usr. In this case, it should be autodetected when you run
493 configure. If PostgreSQL is installed into its default location,
494 `/usr/local/pgsql', you must specify `--site-prefixes=/usr/local/pgsql'
495 when you run configure. If PostgreSQL is installed into another
496 location, use that instead of `/usr/local/pgsql' when specifying
499 As of XEmacs 21.2, PostgreSQL versions 6.5.3 and 7.0 are supported.
500 XEmacs Lisp support for V7.0 is somewhat more extensive than support for
501 V6.5. In particular, asynchronous queries are supported.
504 File: lispref.info, Node: XEmacs PostgreSQL libpq API, Next: XEmacs PostgreSQL libpq Examples, Prev: Building XEmacs with PostgreSQL support, Up: PostgreSQL Support
506 XEmacs PostgreSQL libpq API
507 ===========================
509 The XEmacs PostgreSQL API is intended to be a policy-free, low-level
510 binding to libpq. The intent is to provide all the basic functionality
511 and then let high level Lisp code decide its own policies.
513 This documentation assumes that the reader has knowledge of SQL, but
514 requires no prior knowledge of libpq.
516 There are many examples in this manual and some setup will be
517 required. In order to run most of the following examples, the
518 following code needs to be executed. In addition to the data is in
519 this table, nearly all of the examples will assume that the free
520 variable `P' refers to this database connection. The examples in the
521 original edition of this manual were run against Postgres 7.0beta1.
524 (setq P (pq-connectdb ""))
525 ;; id is the primary key, shikona is a Japanese word that
526 ;; means `the professional name of a Sumo wrestler', and
527 ;; rank is the Sumo rank name.
528 (pq-exec P (concat "CREATE TABLE xemacs_test"
529 " (id int, shikona text, rank text);"))
530 (pq-exec P "COPY xemacs_test FROM stdin;")
531 (pq-put-line P "1\tMusashimaru\tYokuzuna\n")
532 (pq-put-line P "2\tDejima\tOozeki\n")
533 (pq-put-line P "3\tMusoyama\tSekiwake\n")
534 (pq-put-line P "4\tMiyabiyama\tSekiwake\n")
535 (pq-put-line P "5\tWakanoyama\tMaegashira\n")
536 (pq-put-line P "\\.\n")
542 * libpq Lisp Variables::
543 * libpq Lisp Symbols and DataTypes::
544 * Synchronous Interface Functions::
545 * Asynchronous Interface Functions::
546 * Large Object Support::
547 * Other libpq Functions::
548 * Unimplemented libpq Functions::
551 File: lispref.info, Node: libpq Lisp Variables, Next: libpq Lisp Symbols and DataTypes, Prev: XEmacs PostgreSQL libpq API, Up: XEmacs PostgreSQL libpq API
556 Various Unix environment variables are used by libpq to provide
557 defaults to the many different parameters. In the XEmacs Lisp API,
558 these environment variables are bound to Lisp variables to provide more
559 convenient access to Lisp Code. These variables are passed to the
560 backend database server during the establishment of a database
561 connection and when the `pq-setenv' call is made.
564 Initialized from the PGHOST environment variable. The default
568 Initialized from the PGUSER environment variable. The default
571 - Variable: pg:options
572 Initialized from the PGOPTIONS environment variable. Default
573 additional server options.
576 Initialized from the PGPORT environment variable. The default TCP
580 Initialized from the PGTTY environment variable. The default
583 Compatibility note: Debugging TTYs are turned off in the XEmacs
586 - Variable: pg:database
587 Initialized from the PGDATABASE environment variable. The default
588 database to connect to.
591 Initialized from the PGREALM environment variable. The default
594 - Variable: pg:client-encoding
595 Initialized from the PGCLIENTENCODING environment variable. The
596 default client encoding.
598 Compatibility note: This variable is not present in non-Mule
599 XEmacsen. This variable is not present in versions of libpq prior
600 to 7.0. In the current implementation, client encoding is
601 equivalent to the `file-name-coding-system' format.
603 - Variable: pg:authtype
604 Initialized from the PGAUTHTYPE environment variable. The default
605 authentication scheme used.
607 Compatibility note: This variable is unused in versions of libpq
608 after 6.5. It is not implemented at all in the XEmacs Lisp
612 Initialized from the PGGEQO environment variable. Genetic
615 - Variable: pg:cost-index
616 Initialized from the PGCOSTINDEX environment variable. Cost index
619 - Variable: pg:cost-heap
620 Initialized from the PGCOSTHEAP environment variable. Cost heap
624 Initialized from the PGTZ environment variable. Default timezone.
626 - Variable: pg:date-style
627 Initialized from the PGDATESTYLE environment variable. Default
628 date style in returned date objects.
630 - Variable: pg-coding-system
631 This is a variable controlling which coding system is used to
632 encode non-ASCII strings sent to the database.
634 Compatibility Note: This variable is not present in InfoDock.
637 File: lispref.info, Node: libpq Lisp Symbols and DataTypes, Next: Synchronous Interface Functions, Prev: libpq Lisp Variables, Up: XEmacs PostgreSQL libpq API
639 libpq Lisp Symbols and Datatypes
640 --------------------------------
642 The following set of symbols are used to represent the intermediate
643 states involved in the asynchronous interface.
645 - Symbol: pgres::polling-failed
646 Undocumented. A fatal error has occurred during processing of an
647 asynchronous operation.
649 - Symbol: pgres::polling-reading
650 An intermediate status return during an asynchronous operation. It
651 indicates that one may use `select' before polling again.
653 - Symbol: pgres::polling-writing
654 An intermediate status return during an asynchronous operation. It
655 indicates that one may use `select' before polling again.
657 - Symbol: pgres::polling-ok
658 An asynchronous operation has successfully completed.
660 - Symbol: pgres::polling-active
661 An intermediate status return during an asynchronous operation.
662 One can call the poll function again immediately.
664 - Function: pq-pgconn conn field
665 CONN A database connection object. FIELD A symbol indicating
666 which field of PGconn to fetch. Possible values are shown in the
675 Database user's password
678 Hostname database server is running on
681 TCP port number used in the connection
686 Compatibility note: Debugging TTYs are not used in the
690 Additional server options
693 Connection status. Possible return values are shown in the
696 The normal, connected status.
699 The connection is not open and the PGconn object needs
700 to be deleted by `pq-finish'.
702 `pg::connection-started'
703 An asynchronous connection has been started, but is not
706 `pg::connection-made'
707 An asynchronous connect has been made, and there is data
710 `pg::connection-awaiting-response'
711 Awaiting data from the backend during an asynchronous
714 `pg::connection-auth-ok'
715 Received authentication, waiting for the backend to
718 `pg::connection-setenv'
719 Negotiating environment during an asynchronous
723 The last error message that was delivered to this connection.
726 The process ID of the backend database server.
728 The `PGresult' object is used by libpq to encapsulate the results of
729 queries. The printed representation takes on four forms. When the
730 PGresult object contains tuples from an SQL `SELECT' it will look like:
732 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
733 => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
735 The number in brackets indicates how many rows of data are available.
736 When the PGresult object is the result of a command query that doesn't
737 return anything, it will look like:
739 (pq-exec P "CREATE TABLE a_new_table (i int);")
740 => #<PGresult PGRES_COMMAND_OK - CREATE>
742 When either the query is a command-type query that can affect a
743 number of different rows, but doesn't return any of them it will look
747 (pq-exec P "INSERT INTO a_new_table VALUES (1);")
748 (pq-exec P "INSERT INTO a_new_table VALUES (2);")
749 (pq-exec P "INSERT INTO a_new_table VALUES (3);")
750 (setq R (pq-exec P "DELETE FROM a_new_table;")))
751 => #<PGresult PGRES_COMMAND_OK[3] - DELETE 3>
753 Lastly, when the underlying PGresult object has been deallocated
754 directly by `pq-clear' the printed representation will look like:
757 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
762 The following set of functions are accessors to various data in the
765 - Function: pq-result-status result
766 Return status of a query result. RESULT is a PGresult object.
767 The return value is one of the symbols in the following table.
769 A query contained no text. This is usually the result of a
770 recoverable error, or a minor programming error.
773 A query command that doesn't return anything was executed
774 properly by the backend.
777 A query command that returns tuples was executed properly by
781 Copy Out data transfer is in progress.
784 Copy In data transfer is in progress.
786 `pgres::bad-response'
787 An unexpected response was received from the backend.
789 `pgres::nonfatal-error'
790 Undocumented. This value is returned when the libpq function
791 `PQresultStatus' is called with a NULL pointer.
794 Undocumented. An error has occurred in processing the query
795 and the operation was not completed.
797 - Function: pq-res-status result
798 Return the query result status as a string, not a symbol. RESULT
799 is a PGresult object.
801 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
802 => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
806 - Function: pq-result-error-message result
807 Return an error message generated by the query, if any. RESULT is
810 (setq R (pq-exec P "SELECT * FROM xemacs-test;"))
811 => <A fatal error is signaled in the echo area>
812 (pq-result-error-message R)
813 => "ERROR: parser: parse error at or near \"-\"
816 - Function: pq-ntuples result
817 Return the number of tuples in the query result. RESULT is a
820 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
821 => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
825 - Function: pq-nfields result
826 Return the number of fields in each tuple of the query result.
827 RESULT is a PGresult object.
829 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
830 => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
834 - Function: pq-binary-tuples result
835 Returns t if binary tuples are present in the results, nil
836 otherwise. RESULT is a PGresult object.
838 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
839 => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
843 - Function: pq-fname result field-index
844 Returns the name of a specific field. RESULT is a PGresult object.
845 FIELD-INDEX is the number of the column to select from. The first
846 column is number zero.
849 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
850 (setq i (pq-nfields R))
851 (while (>= (decf i) 0)
852 (push (pq-fname R i) l))
854 => ("id" "shikona" "rank")
856 - Function: pq-fnumber result field-name
857 Return the field number corresponding to the given field name. -1
858 is returned on a bad field name. RESULT is a PGresult object.
859 FIELD-NAME is a string representing the field name to find.
860 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
861 => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
864 (pq-fnumber R "Not a field")
867 - Function: pq-ftype result field-num
868 Return an integer code representing the data type of the specified
869 column. RESULT is a PGresult object. FIELD-NUM is the field
872 The return value of this function is the Object ID (Oid) in the
873 database of the type. Further queries need to be made to various
874 system tables in order to convert this value into something useful.
876 - Function: pq-fmod result field-num
877 Return the type modifier code associated with a field. Field
878 numbers start at zero. RESULT is a PGresult object. FIELD-INDEX
879 selects which field to use.
881 - Function: pq-fsize result field-index
882 Return size of the given field. RESULT is a PGresult object.
883 FIELD-INDEX selects which field to use.
886 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
887 (setq i (pq-nfields R))
888 (while (>= (decf i) 0)
889 (push (list (pq-ftype R i) (pq-fsize R i)) l))
891 => ((23 23) (25 25) (25 25))
893 - Function: pq-get-value result tup-num field-num
894 Retrieve a return value. RESULT is a PGresult object. TUP-NUM
895 selects which tuple to fetch from. FIELD-NUM selects which field
898 Both tuples and fields are numbered from zero.
900 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
901 => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
909 - Function: pq-get-length result tup-num field-num
910 Return the length of a specific value. RESULT is a PGresult
911 object. TUP-NUM selects which tuple to fetch from. FIELD-NUM
912 selects which field to fetch from.
914 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
915 => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
916 (pq-get-length R 0 1)
918 (pq-get-length R 1 1)
920 (pq-get-length R 2 1)
923 - Function: pq-get-is-null result tup-num field-num
924 Return t if the specific value is the SQL NULL. RESULT is a
925 PGresult object. TUP-NUM selects which tuple to fetch from.
926 FIELD-NUM selects which field to fetch from.
928 - Function: pq-cmd-status result
929 Return a summary string from the query. RESULT is a PGresult
931 (pq-exec P "INSERT INTO xemacs_test
932 VALUES (6, 'Wakanohana', 'Yokozuna');")
933 => #<PGresult PGRES_COMMAND_OK[1] - INSERT 542086 1>
936 (setq R (pq-exec P "UPDATE xemacs_test SET rank='retired'
937 WHERE shikona='Wakanohana';"))
938 => #<PGresult PGRES_COMMAND_OK[1] - UPDATE 1>
942 Note that the first number returned from an insertion, like in the
943 example, is an object ID number and will almost certainly vary from
944 system to system since object ID numbers in Postgres must be unique
945 across all databases.
947 - Function: pq-cmd-tuples result
948 Return the number of tuples if the last command was an
949 INSERT/UPDATE/DELETE. If the last command was something else, the
950 empty string is returned. RESULT is a PGresult object.
952 (setq R (pq-exec P "INSERT INTO xemacs_test VALUES
953 (7, 'Takanohana', 'Yokuzuna');"))
954 => #<PGresult PGRES_COMMAND_OK[1] - INSERT 38688 1>
957 (setq R (pq-exec P "SELECT * from xemacs_test;"))
958 => #<PGresult PGRES_TUPLES_OK[7] - SELECT>
961 (setq R (pq-exec P "DELETE FROM xemacs_test
962 WHERE shikona LIKE '%hana';"))
963 => #<PGresult PGRES_COMMAND_OK[2] - DELETE 2>
967 - Function: pq-oid-value result
968 Return the object id of the insertion if the last command was an
969 INSERT. 0 is returned if the last command was not an insertion.
970 RESULT is a PGresult object.
972 In the first example, the numbers you will see on your local
973 system will almost certainly be different, however the second
974 number from the right in the unprintable PGresult object and the
975 number returned by `pq-oid-value' should match.
976 (setq R (pq-exec P "INSERT INTO xemacs_test VALUES
977 (8, 'Terao', 'Maegashira');"))
978 => #<PGresult PGRES_COMMAND_OK[1] - INSERT 542089 1>
981 (setq R (pq-exec P "SELECT shikona FROM xemacs_test
982 WHERE rank='Maegashira';"))
983 => #<PGresult PGRES_TUPLES_OK[2] - SELECT>
987 - Function: pq-make-empty-pgresult conn status
988 Create an empty pgresult with the given status. CONN a database
989 connection object STATUS a value that can be returned by
992 The caller is responsible for making sure the return value gets
996 File: lispref.info, Node: Synchronous Interface Functions, Next: Asynchronous Interface Functions, Prev: libpq Lisp Symbols and DataTypes, Up: XEmacs PostgreSQL libpq API
998 Synchronous Interface Functions
999 -------------------------------
1001 - Function: pq-connectdb conninfo
1002 Establish a (synchronous) database connection. CONNINFO A string
1003 of blank separated options. Options are of the form "OPTION =
1004 VALUE". If VALUE contains blanks, it must be single quoted.
1005 Blanks around the equal sign are optional. Multiple option
1006 assignments are blank separated.
1007 (pq-connectdb "dbname=japanese port = 25432")
1008 => #<PGconn localhost:25432 steve/japanese>
1009 The printed representation of a database connection object has four
1010 fields. The first field is the hostname where the database server
1011 is running (in this case localhost), the second field is the port
1012 number, the third field is the database user name, and the fourth
1013 field is the name of the database.
1015 Database connection objects which have been disconnected and will
1016 generate an immediate error if they are used look like:
1018 Bad connections can be reestablished with `pq-reset', or deleted
1019 entirely with `pq-finish'.
1021 A database connection object that has been deleted looks like:
1022 (let ((P1 (pq-connectdb "")))
1027 Note that database connection objects are the most heavy weight
1028 objects in XEmacs Lisp at this writing, usually representing as
1029 much as several megabytes of virtual memory on the machine the
1030 database server is running on. It is wisest to explicitly delete
1031 them when you are finished with them, rather than letting garbage
1032 collection do it. An example idiom is:
1034 (let ((P (pq-connectiondb "")))
1037 (...)) ; access database here
1040 The following options are available in the options string:
1042 Authentication type. Same as PGAUTHTYPE. This is no longer
1046 Database user name. Same as PGUSER.
1052 Database name. Same as PGDATABASE
1055 Symbolic hostname. Same as PGHOST.
1058 Host address as four octets (eg. like 192.168.1.1).
1061 TCP port to connect to. Same as PGPORT.
1064 Debugging TTY. Same as PGTTY. This value is suppressed in
1065 the XEmacs Lisp API.
1068 Extra backend database options. Same as PGOPTIONS. A
1069 database connection object is returned regardless of whether a
1070 connection was established or not.
1072 - Function: pq-reset conn
1073 Reestablish database connection. CONN A database connection
1076 This function reestablishes a database connection using the
1077 original connection parameters. This is useful if something has
1078 happened to the TCP link and it has become broken.
1080 - Function: pq-exec conn query
1081 Make a synchronous database query. CONN A database connection
1082 object. QUERY A string containing an SQL query. A PGresult
1083 object is returned, which in turn may be queried by its many
1084 accessor functions to retrieve state out of it. If the query
1085 string contains multiple SQL commands, only results from the final
1086 command are returned.
1088 (setq R (pq-exec P "SELECT * FROM xemacs_test;
1089 DELETE FROM xemacs_test WHERE id=8;"))
1090 => #<PGresult PGRES_COMMAND_OK[1] - DELETE 1>
1092 - Function: pq-notifies conn
1093 Return the latest async notification that has not yet been handled.
1094 CONN A database connection object. If there has been a
1095 notification, then a list of two elements will be returned. The
1096 first element contains the relation name being notified, the second
1097 element contains the backend process ID number. nil is returned
1098 if there aren't any notifications to process.
1100 - Function: PQsetenv conn
1101 Synchronous transfer of environment variables to a backend CONN A
1102 database connection object.
1104 Environment variable transfer is done as a normal part of database
1107 Compatibility note: This function was present but not documented
1108 in versions of libpq prior to 7.0.
1111 File: lispref.info, Node: Asynchronous Interface Functions, Next: Large Object Support, Prev: Synchronous Interface Functions, Up: XEmacs PostgreSQL libpq API
1113 Asynchronous Interface Functions
1114 --------------------------------
1116 Making command by command examples is too complex with the
1117 asynchronous interface functions. See the examples section for
1118 complete calling sequences.
1120 - Function: pq-connect-start conninfo
1121 Begin establishing an asynchronous database connection. CONNINFO
1122 A string containing the connection options. See the documentation
1123 of `pq-connectdb' for a listing of all the available flags.
1125 - Function: pq-connect-poll conn
1126 An intermediate function to be called during an asynchronous
1127 database connection. CONN A database connection object. The
1128 result codes are documented in a previous section.
1130 - Function: pq-is-busy conn
1131 Returns t if `pq-get-result' would block waiting for input. CONN
1132 A database connection object.
1134 - Function: pq-consume-input conn
1135 Consume any available input from the backend. CONN A database
1138 Nil is returned if anything bad happens.
1140 - Function: pq-reset-start conn
1141 Reset connection to the backend asynchronously. CONN A database
1144 - Function: pq-reset-poll conn
1145 Poll an asynchronous reset for completion CONN A database
1148 - Function: pq-reset-cancel conn
1149 Attempt to request cancellation of the current operation. CONN A
1150 database connection object.
1152 The return value is t if the cancel request was successfully
1153 dispatched, nil if not (in which case conn->errorMessage is set).
1154 Note: successful dispatch is no guarantee that there will be any
1155 effect at the backend. The application must read the operation
1158 - Function: pq-send-query conn query
1159 Submit a query to Postgres and don't wait for the result. CONN A
1160 database connection object. Returns: t if successfully submitted
1161 nil if error (conn->errorMessage is set)
1163 - Function: pq-get-result conn
1164 Retrieve an asynchronous result from a query. CONN A database
1167 NIL is returned when no more query work remains.
1169 - Function: pq-set-nonblocking conn arg
1170 Sets the PGconn's database connection non-blocking if the arg is
1171 TRUE or makes it non-blocking if the arg is FALSE, this will not
1172 protect you from PQexec(), you'll only be safe when using the
1173 non-blocking API. CONN A database connection object.
1175 - Function: pq-is-nonblocking conn
1176 Return the blocking status of the database connection CONN A
1177 database connection object.
1179 - Function: pq-flush conn
1180 Force the write buffer to be written (or at least try) CONN A
1181 database connection object.
1183 - Function: PQsetenvStart conn
1184 Start asynchronously passing environment variables to a backend.
1185 CONN A database connection object.
1187 Compatibility note: this function is only available with libpq-7.0.
1189 - Function: PQsetenvPoll conn
1190 Check an asynchronous environment variables transfer for
1191 completion. CONN A database connection object.
1193 Compatibility note: this function is only available with libpq-7.0.
1195 - Function: PQsetenvAbort conn
1196 Attempt to terminate an asynchronous environment variables
1197 transfer. CONN A database connection object.
1199 Compatibility note: this function is only available with libpq-7.0.
1202 File: lispref.info, Node: Large Object Support, Next: Other libpq Functions, Prev: Asynchronous Interface Functions, Up: XEmacs PostgreSQL libpq API
1204 Large Object Support
1205 --------------------
1207 - Function: pq-lo-import conn filename
1208 Import a file as a large object into the database. CONN a
1209 database connection object FILENAME filename to import
1211 On success, the object id is returned.
1213 - Function: pq-lo-export conn oid filename
1214 Copy a large object in the database into a file. CONN a database
1215 connection object. OID object id number of a large object.
1216 FILENAME filename to export to.
1219 File: lispref.info, Node: Other libpq Functions, Next: Unimplemented libpq Functions, Prev: Large Object Support, Up: XEmacs PostgreSQL libpq API
1221 Other libpq Functions
1222 ---------------------
1224 - Function: pq-finish conn
1225 Destroy a database connection object by calling free on it. CONN
1226 a database connection object
1228 It is possible to not call this routine because the usual XEmacs
1229 garbage collection mechanism will call the underlying libpq
1230 routine whenever it is releasing stale `PGconn' objects. However,
1231 this routine is useful in `unwind-protect' clauses to make
1232 connections go away quickly when unrecoverable errors have
1235 After calling this routine, the printed representation of the
1236 XEmacs wrapper object will contain the string "DEAD".
1238 - Function: pq-client-encoding conn
1239 Return the client encoding as an integer code. CONN a database
1242 (pq-client-encoding P)
1245 Compatibility note: This function did not exist prior to libpq-7.0
1246 and does not exist in a non-Mule XEmacs.
1248 - Function: pq-set-client-encoding conn encoding
1249 Set client coding system. CONN a database connection object
1250 ENCODING a string representing the desired coding system
1252 (pq-set-client-encoding P "EUC_JP")
1255 The current idiom for ensuring proper coding system conversion is
1256 the following (illustrated for EUC Japanese encoding):
1257 (setq P (pq-connectdb "..."))
1258 (let ((file-name-coding-system 'euc-jp)
1259 (pg-coding-system 'euc-jp))
1260 (pq-set-client-encoding "EUC_JP")
1263 Compatibility note: This function did not exist prior to libpq-7.0
1264 and does not exist in a non-Mule XEmacs.
1266 - Function: pq-env-2-encoding
1267 Return the integer code representing the coding system in
1272 Compatibility note: This function did not exist prior to libpq-7.0
1273 and does not exist in a non-Mule XEmacs.
1275 - Function: pq-clear res
1276 Destroy a query result object by calling free() on it. RES a
1279 Note: The memory allocation systems of libpq and XEmacs are
1280 different. The XEmacs representation of a query result object
1281 will have both the XEmacs version and the libpq version freed at
1282 the next garbage collection when the object is no longer being
1283 referenced. Calling this function does not release the XEmacs
1284 object, it is still subject to the usual rules for Lisp objects.
1285 The printed representation of the XEmacs object will contain the
1286 string "DEAD" after this routine is called indicating that it is no
1287 longer useful for anything.
1289 - Function: pq-conn-defaults
1290 Return a data structure that represents the connection defaults.
1291 The data is returned as a list of lists, where each sublist
1292 contains info regarding a single option.