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.so
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 should have XEmacs PostgreSQL support by default. If you are
488 building XEmacs from source on a Linux system with PostgreSQL installed
489 into the default location, it should be autodetected when you run
490 configure. If you have installed PostgreSQL into its non-Linux default
491 location, `/usr/local/pgsql', you must specify
492 `--site-prefixes=/usr/local/pgsql' when you run configure. If you
493 installed PostgreSQL into another location, use that instead of
494 `/usr/local/pgsql' when specifying `--site-prefixes'.
496 As of XEmacs 21.2, PostgreSQL versions 6.5.3 and 7.0 are supported.
497 XEmacs Lisp support for V7.0 is somewhat more extensive than support for
498 V6.5. In particular, asynchronous queries are supported.
501 File: lispref.info, Node: XEmacs PostgreSQL libpq API, Next: XEmacs PostgreSQL libpq Examples, Prev: Building XEmacs with PostgreSQL support, Up: PostgreSQL Support
503 XEmacs PostgreSQL libpq API
504 ===========================
506 XEmacs PostgreSQL API is intended to be a policy-free, low-level
507 binding to libpq. The intent is to provide all the basic functionality
508 and then let high level Lisp code decide its own policies.
510 This documentation assumes that the reader has knowledge of SQL, but
511 requires no prior knowledge of libpq.
513 There are many examples in this manual and some setup will be
514 required. In order to run most of the following examples, the
515 following code needs to be executed. In addition to the data is in
516 this table, nearly all of the examples will assume that the free
517 variable `P' refers to this database connection. The examples in the
518 original edition of this manual were run against Postgres 7.0beta1.
521 (setq P (pq-connectdb ""))
522 ;; id is the primary key, shikona is a Japanese word that
523 ;; means `the professional name of a Sumo wrestler', and
524 ;; rank is the Sumo rank name.
525 (pq-exec P (concat "CREATE TABLE xemacs_test"
526 " (id int, shikona text, rank text);"))
527 (pq-exec P "COPY xemacs_test FROM stdin;")
528 (pq-put-line P "1\tMusashimaru\tYokuzuna\n")
529 (pq-put-line P "2\tDejima\tOozeki\n")
530 (pq-put-line P "3\tMusoyama\tSekiwake\n")
531 (pq-put-line P "4\tMiyabiyama\tSekiwake\n")
532 (pq-put-line P "5\tWakanoyama\tMaegashira\n")
533 (pq-put-line P "\\.\n")
539 * libpq Lisp Variables::
540 * libpq Lisp Symbols and DataTypes::
541 * Synchronous Interface Functions::
542 * Asynchronous Interface Functions::
543 * Large Object Support::
544 * Other libpq Functions::
545 * Unimplemented libpq Functions::
548 File: lispref.info, Node: libpq Lisp Variables, Next: libpq Lisp Symbols and DataTypes, Prev: XEmacs PostgreSQL libpq API, Up: XEmacs PostgreSQL libpq API
553 Various Unix environment variables are used by libpq to provide
554 defaults to the many different parameters. In the XEmacs Lisp API,
555 these environment variables are bound to Lisp variables to provide more
556 convenient access to Lisp Code. These variables are passed to the
557 backend database server during the establishment of a database
558 connection and when the `pq-setenv' call is made.
561 Initialized from the PGHOST environment variable. The default
565 Initialized from the PGUSER environment variable. The default
568 - Variable: pg:options
569 Initialized from the PGOPTIONS environment variable. Default
570 additional server options.
573 Initialized from the PGPORT environment variable. The default TCP
577 Initialized from the PGTTY environment variable. The default
580 Compatibility note: Debugging TTYs are turned off in the XEmacs
583 - Variable: pg:database
584 Initialized from the PGDATABASE environment variable. The default
585 database to connect to.
588 Initialized from the PGREALM environment variable. The default
591 - Variable: pg:client-encoding
592 Initialized from the PGCLIENTENCODING environment variable. The
593 default client encoding.
595 Compatibility note: This variable is not present in non-Mule
596 XEmacsen. This variable is not present in versions of libpq prior
597 to 7.0. In the current implementation, client encoding is
598 equivalent to the `file-name-coding-system' format.
600 - Variable: pg:authtype
601 Initialized from the PGAUTHTYPE environment variable. The default
602 authentication scheme used.
604 Compatibility note: This variable is unused in versions of libpq
605 after 6.5. It is not implemented at all in the XEmacs Lisp
609 Initialized from the PGGEQO environment variable. Genetic
612 - Variable: pg:cost-index
613 Initialized from the PGCOSTINDEX environment variable. Cost index
616 - Variable: pg:cost-heap
617 Initialized from the PGCOSTHEAP environment variable. Cost heap
621 Initialized from the PGTZ environment variable. Default timezone.
623 - Variable: pg:date-style
624 Initialized from the PGDATESTYLE environment variable. Default
625 date style in returned date objects.
627 - Variable: pg-coding-system
628 This is a variable controlling which coding system is used to
629 encode non-ASCII strings sent to the database.
631 Compatibility Note: This variable is not present in InfoDock.
634 File: lispref.info, Node: libpq Lisp Symbols and DataTypes, Next: Synchronous Interface Functions, Prev: libpq Lisp Variables, Up: XEmacs PostgreSQL libpq API
636 libpq Lisp Symbols and Datatypes
637 --------------------------------
639 The following set of symbols are used to represent the intermediate
640 states involved in the asynchronous interface.
642 - Symbol: pgres::polling-failed
643 Undocumented. A fatal error has occurred during processing of an
644 asynchronous operation.
646 - Symbol: pgres::polling-reading
647 An intermediate status return during an asynchronous operation. It
648 indicates that one may use `select' before polling again.
650 - Symbol: pgres::polling-writing
651 An intermediate status return during an asynchronous operation. It
652 indicates that one may use `select' before polling again.
654 - Symbol: pgres::polling-ok
655 An asynchronous operation has successfully completed.
657 - Symbol: pgres::polling-active
658 An intermediate status return during an asynchronous operation.
659 One can call the poll function again immediately.
661 - Function: pq-pgconn conn field
662 CONN A database connection object. FIELD A symbol indicating
663 which field of PGconn to fetch. Possible values are shown in the
672 Database user's password
675 Hostname database server is running on
678 TCP port number used in the connection
683 Compatibility note: Debugging TTYs are not used in the
687 Additional server options
690 Connection status. Possible return values are shown in the
693 The normal, connected status.
696 The connection is not open and the PGconn object needs
697 to be deleted by `pq-finish'.
699 `pg::connection-started'
700 An asynchronous connection has been started, but is not
703 `pg::connection-made'
704 An asynchronous connect has been made, and there is data
707 `pg::connection-awaiting-response'
708 Awaiting data from the backend during an asynchronous
711 `pg::connection-auth-ok'
712 Received authentication, waiting for the backend to
715 `pg::connection-setenv'
716 Negotiating environment during an asynchronous
720 The last error message that was delivered to this connection.
723 The process ID of the backend database server.
725 The `PGresult' object is used by libpq to encapsulate the results of
726 queries. The printed representation takes on four forms. When the
727 PGresult object contains tuples from an SQL `SELECT' it will look like:
729 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
730 => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
732 The number in brackets indicates how many rows of data are available.
733 When the PGresult object is the result of a command query that doesn't
734 return anything, it will look like:
736 (pq-exec P "CREATE TABLE a_new_table (i int);")
737 => #<PGresult PGRES_COMMAND_OK - CREATE>
739 When either the query is a command-type query that can affect a
740 number of different rows, but doesn't return any of them it will look
744 (pq-exec P "INSERT INTO a_new_table VALUES (1);")
745 (pq-exec P "INSERT INTO a_new_table VALUES (2);")
746 (pq-exec P "INSERT INTO a_new_table VALUES (3);")
747 (setq R (pq-exec P "DELETE FROM a_new_table;")))
748 => #<PGresult PGRES_COMMAND_OK[3] - DELETE 3>
750 Lastly, when the underlying PGresult object has been deallocated
751 directly by `pq-clear' the printed representation will look like:
754 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
759 The following set of functions are accessors to various data in the
762 - Function: pq-result-status result
763 Return status of a query result. RESULT is a PGresult object.
764 The return value is one of the symbols in the following table.
766 A query contained no text. This is usually the result of a
767 recoverable error, or a minor programming error.
770 A query command that doesn't return anything was executed
771 properly by the backend.
774 A query command that returns tuples was executed properly by
778 Copy Out data transfer is in progress.
781 Copy In data transfer is in progress.
783 `pgres::bad-response'
784 An unexpected response was received from the backend.
786 `pgres::nonfatal-error'
787 Undocumented. This value is returned when the libpq function
788 `PQresultStatus' is called with a NULL pointer.
791 Undocumented. An error has occurred in processing the query
792 and the operation was not completed.
794 - Function: pq-res-status result
795 Return the query result status as a string, not a symbol. RESULT
796 is a PGresult object.
798 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
799 => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
803 - Function: pq-result-error-message result
804 Return an error message generated by the query, if any. RESULT is
807 (setq R (pq-exec P "SELECT * FROM xemacs-test;"))
808 => <A fatal error is signaled in the echo area>
809 (pq-result-error-message R)
810 => "ERROR: parser: parse error at or near \"-\"
813 - Function: pq-ntuples result
814 Return the number of tuples in the query result. RESULT is a
817 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
818 => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
822 - Function: pq-nfields result
823 Return the number of fields in each tuple of the query result.
824 RESULT is a PGresult object.
826 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
827 => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
831 - Function: pq-binary-tuples result
832 Returns t if binary tuples are present in the results, nil
833 otherwise. RESULT is a PGresult object.
835 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
836 => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
840 - Function: pq-fname result field-index
841 Returns the name of a specific field. RESULT is a PGresult object.
842 FIELD-INDEX is the number of the column to select from. The first
843 column is number zero.
846 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
847 (setq i (pq-nfields R))
848 (while (>= (decf i) 0)
849 (push (pq-fname R i) l))
851 => ("id" "shikona" "rank")
853 - Function: pq-fnumber result field-name
854 Return the field number corresponding to the given field name. -1
855 is returned on a bad field name. RESULT is a PGresult object.
856 FIELD-NAME is a string representing the field name to find.
857 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
858 => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
861 (pq-fnumber R "Not a field")
864 - Function: pq-ftype result field-num
865 Return an integer code representing the data type of the specified
866 column. RESULT is a PGresult object. FIELD-NUM is the field
869 The return value of this function is the Object ID (Oid) in the
870 database of the type. Further queries need to be made to various
871 system tables in order to convert this value into something useful.
873 - Function: pq-fmod result field-num
874 Return the type modifier code associated with a field. Field
875 numbers start at zero. RESULT is a PGresult object. FIELD-INDEX
876 selects which field to use.
878 - Function: pq-fsize result field-index
879 Return size of the given field. RESULT is a PGresult object.
880 FIELD-INDEX selects which field to use.
883 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
884 (setq i (pq-nfields R))
885 (while (>= (decf i) 0)
886 (push (list (pq-ftype R i) (pq-fsize R i)) l))
888 => ((23 23) (25 25) (25 25))
890 - Function: pq-get-value result tup-num field-num
891 Retrieve a return value. RESULT is a PGresult object. TUP-NUM
892 selects which tuple to fetch from. FIELD-NUM selects which field
895 Both tuples and fields are numbered from zero.
897 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
898 => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
906 - Function: pq-get-length result tup-num field-num
907 Return the length of a specific value. RESULT is a PGresult
908 object. TUP-NUM selects which tuple to fetch from. FIELD-NUM
909 selects which field to fetch from.
911 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
912 => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
913 (pq-get-length R 0 1)
915 (pq-get-length R 1 1)
917 (pq-get-length R 2 1)
920 - Function: pq-get-is-null result tup-num field-num
921 Return t if the specific value is the SQL NULL. RESULT is a
922 PGresult object. TUP-NUM selects which tuple to fetch from.
923 FIELD-NUM selects which field to fetch from.
925 - Function: pq-cmd-status result
926 Return a summary string from the query. RESULT is a PGresult
928 (pq-exec P "INSERT INTO xemacs_test
929 VALUES (6, 'Wakanohana', 'Yokozuna');")
930 => #<PGresult PGRES_COMMAND_OK[1] - INSERT 542086 1>
933 (setq R (pq-exec P "UPDATE xemacs_test SET rank='retired'
934 WHERE shikona='Wakanohana';"))
935 => #<PGresult PGRES_COMMAND_OK[1] - UPDATE 1>
939 Note that the first number returned from an insertion, like in the
940 example, is an object ID number and will almost certainly vary from
941 system to system since object ID numbers in Postgres must be unique
942 across all databases.
944 - Function: pq-cmd-tuples result
945 Return the number of tuples if the last command was an
946 INSERT/UPDATE/DELETE. If the last command was something else, the
947 empty string is returned. RESULT is a PGresult object.
949 (setq R (pq-exec P "INSERT INTO xemacs_test VALUES
950 (7, 'Takanohana', 'Yokuzuna');"))
951 => #<PGresult PGRES_COMMAND_OK[1] - INSERT 38688 1>
954 (setq R (pq-exec P "SELECT * from xemacs_test;"))
955 => #<PGresult PGRES_TUPLES_OK[7] - SELECT>
958 (setq R (pq-exec P "DELETE FROM xemacs_test
959 WHERE shikona LIKE '%hana';"))
960 => #<PGresult PGRES_COMMAND_OK[2] - DELETE 2>
964 - Function: pq-oid-value result
965 Return the object id of the insertion if the last command was an
966 INSERT. 0 is returned if the last command was not an insertion.
967 RESULT is a PGresult object.
969 In the first example, the numbers you will see on your local
970 system will almost certainly be different, however the second
971 number from the right in the unprintable PGresult object and the
972 number returned by `pq-oid-value' should match.
973 (setq R (pq-exec P "INSERT INTO xemacs_test VALUES
974 (8, 'Terao', 'Maegashira');"))
975 => #<PGresult PGRES_COMMAND_OK[1] - INSERT 542089 1>
978 (setq R (pq-exec P "SELECT shikona FROM xemacs_test
979 WHERE rank='Maegashira';"))
980 => #<PGresult PGRES_TUPLES_OK[2] - SELECT>
984 - Function: pq-make-empty-pgresult conn status
985 Create an empty pgresult with the given status. CONN a database
986 connection object STATUS a value that can be returned by
989 The caller is responsible for making sure the return value gets
993 File: lispref.info, Node: Synchronous Interface Functions, Next: Asynchronous Interface Functions, Prev: libpq Lisp Symbols and DataTypes, Up: XEmacs PostgreSQL libpq API
995 Synchronous Interface Functions
996 -------------------------------
998 - Function: pq-connectdb conninfo
999 Establish a (synchronous) database connection. CONNINFO A string
1000 of blank separated options. Options are of the form "OPTION =
1001 VALUE". If VALUE contains blanks, it must be single quoted.
1002 Blanks around the equal sign are optional. Multiple option
1003 assignments are blank separated.
1004 (pq-connectdb "dbname=japanese port = 25432")
1005 => #<PGconn localhost:25432 steve/japanese>
1006 The printed representation of a database connection object has four
1007 fields. The first field is the hostname where the database server
1008 is running (in this case localhost), the second field is the port
1009 number, the third field is the database user name, and the fourth
1010 field is the name of the database.
1012 Database connection objects which have been disconnected and will
1013 generate an immediate error if they are used look like:
1015 Bad connections can be reestablished with `pq-reset', or deleted
1016 entirely with `pq-finish'.
1018 A database connection object that has been deleted looks like:
1019 (let ((P1 (pq-connectdb "")))
1024 Note that database connection objects are the most heavy weight
1025 objects in XEmacs Lisp at this writing, usually representing as
1026 much as several megabytes of virtual memory on the machine the
1027 database server is running on. It is wisest to explicitly delete
1028 them when you are finished with them, rather than letting garbage
1029 collection do it. An example idiom is:
1031 (let ((P (pq-connectiondb "")))
1034 (...)) ; access database here
1037 The following options are available in the options string:
1039 Authentication type. Same as PGAUTHTYPE. This is no longer
1043 Database user name. Same as PGUSER.
1049 Database name. Same as PGDATABASE
1052 Symbolic hostname. Same as PGHOST.
1055 Host address as four octets (eg. like 192.168.1.1).
1058 TCP port to connect to. Same as PGPORT.
1061 Debugging TTY. Same as PGTTY. This value is suppressed in
1062 the XEmacs Lisp API.
1065 Extra backend database options. Same as PGOPTIONS. A
1066 database connection object is returned regardless of whether a
1067 connection was established or not.
1069 - Function: pq-reset conn
1070 Reestablish database connection. CONN A database connection
1073 This function reestablishes a database connection using the
1074 original connection parameters. This is useful if something has
1075 happened to the TCP link and it has become broken.
1077 - Function: pq-exec conn query
1078 Make a synchronous database query. CONN A database connection
1079 object. QUERY A string containing an SQL query. A PGresult
1080 object is returned, which in turn may be queried by its many
1081 accessor functions to retrieve state out of it. If the query
1082 string contains multiple SQL commands, only results from the final
1083 command are returned.
1085 (setq R (pq-exec P "SELECT * FROM xemacs_test;
1086 DELETE FROM xemacs_test WHERE id=8;"))
1087 => #<PGresult PGRES_COMMAND_OK[1] - DELETE 1>
1089 - Function: pq-notifies conn
1090 Return the latest async notification that has not yet been handled.
1091 CONN A database connection object. If there has been a
1092 notification, then a list of two elements will be returned. The
1093 first element contains the relation name being notified, the second
1094 element contains the backend process ID number. nil is returned
1095 if there aren't any notifications to process.
1097 - Function: PQsetenv conn
1098 Synchronous transfer of environment variables to a backend CONN A
1099 database connection object.
1101 Environment variable transfer is done as a normal part of database
1104 Compatibility note: This function was present but not documented
1105 in versions of libpq prior to 7.0.
1108 File: lispref.info, Node: Asynchronous Interface Functions, Next: Large Object Support, Prev: Synchronous Interface Functions, Up: XEmacs PostgreSQL libpq API
1110 Asynchronous Interface Functions
1111 --------------------------------
1113 Making command by command examples is too complex with the
1114 asynchronous interface functions. See the examples section for
1115 complete calling sequences.
1117 - Function: pq-connect-start conninfo
1118 Begin establishing an asynchronous database connection. CONNINFO
1119 A string containing the connection options. See the documentation
1120 of `pq-connectdb' for a listing of all the available flags.
1122 - Function: pq-connect-poll conn
1123 An intermediate function to be called during an asynchronous
1124 database connection. CONN A database connection object. The
1125 result codes are documented in a previous section.
1127 - Function: pq-is-busy conn
1128 Returns t if `pq-get-result' would block waiting for input. CONN
1129 A database connection object.
1131 - Function: pq-consume-input conn
1132 Consume any available input from the backend. CONN A database
1135 Nil is returned if anything bad happens.
1137 - Function: pq-reset-start conn
1138 Reset connection to the backend asynchronously. CONN A database
1141 - Function: pq-reset-poll conn
1142 Poll an asynchronous reset for completion CONN A database
1145 - Function: pq-reset-cancel conn
1146 Attempt to request cancellation of the current operation. CONN A
1147 database connection object.
1149 The return value is t if the cancel request was successfully
1150 dispatched, nil if not (in which case conn->errorMessage is set).
1151 Note: successful dispatch is no guarantee that there will be any
1152 effect at the backend. The application must read the operation
1155 - Function: pq-send-query conn query
1156 Submit a query to Postgres and don't wait for the result. CONN A
1157 database connection object. Returns: t if successfully submitted
1158 nil if error (conn->errorMessage is set)
1160 - Function: pq-get-result conn
1161 Retrieve an asynchronous result from a query. CONN A database
1164 NIL is returned when no more query work remains.
1166 - Function: pq-set-nonblocking conn arg
1167 Sets the PGconn's database connection non-blocking if the arg is
1168 TRUE or makes it non-blocking if the arg is FALSE, this will not
1169 protect you from PQexec(), you'll only be safe when using the
1170 non-blocking API. CONN A database connection object.
1172 - Function: pq-is-nonblocking conn
1173 Return the blocking status of the database connection CONN A
1174 database connection object.
1176 - Function: pq-flush conn
1177 Force the write buffer to be written (or at least try) CONN A
1178 database connection object.
1180 - Function: PQsetenvStart conn
1181 Start asynchronously passing environment variables to a backend.
1182 CONN A database connection object.
1184 Compatibility note: this function is only available with libpq-7.0.
1186 - Function: PQsetenvPoll conn
1187 Check an asynchronous enviroment variables transfer for completion.
1188 CONN A database connection object.
1190 Compatibility note: this function is only available with libpq-7.0.
1192 - Function: PQsetenvAbort conn
1193 Attempt to terminate an asynchronous environment variables
1194 transfer. CONN A database connection object.
1196 Compatibility note: this function is only available with libpq-7.0.
1199 File: lispref.info, Node: Large Object Support, Next: Other libpq Functions, Prev: Asynchronous Interface Functions, Up: XEmacs PostgreSQL libpq API
1201 Large Object Support
1202 --------------------
1204 - Function: pq-lo-import conn filename
1205 Import a file as a large object into the database. CONN a
1206 database connection object FILENAME filename to import
1208 On success, the object id is returned.
1210 - Function: pq-lo-export conn oid filename
1211 Copy a large object in the database into a file. CONN a database
1212 connection object. OID object id number of a large object.
1213 FILENAME filename to export to.
1216 File: lispref.info, Node: Other libpq Functions, Next: Unimplemented libpq Functions, Prev: Large Object Support, Up: XEmacs PostgreSQL libpq API
1218 Other libpq Functions
1219 ---------------------
1221 - Function: pq-finish conn
1222 Destroy a database connection object by calling free on it. CONN
1223 a database connection object
1225 It is possible to not call this routine because the usual XEmacs
1226 garbage collection mechanism will call the underlying libpq
1227 routine whenever it is releasing stale `PGconn' objects. However,
1228 this routine is useful in `unwind-protect' clauses to make
1229 connections go away quickly when unrecoverable errors have
1232 After calling this routine, the printed representation of the
1233 XEmacs wrapper object will contain the string "DEAD".
1235 - Function: pq-client-encoding conn
1236 Return the client encoding as an integer code. CONN a database
1239 (pq-client-encoding P)
1242 Compatibility note: This function did not exist prior to libpq-7.0
1243 and does not exist in a non-Mule XEmacs.
1245 - Function: pq-set-client-encoding conn encoding
1246 Set client coding system. CONN a database connection object
1247 ENCODING a string representing the desired coding system
1249 (pq-set-client-encoding P "EUC_JP")
1252 The current idiom for ensuring proper coding system conversion is
1253 the following (illustrated for EUC Japanese encoding):
1254 (setq P (pq-connectdb "..."))
1255 (let ((file-name-coding-system 'euc-jp)
1256 (pg-coding-system 'euc-jp))
1257 (pq-set-client-encoding "EUC_JP")
1260 Compatibility note: This function did not exist prior to libpq-7.0
1261 and does not exist in a non-Mule XEmacs.
1263 - Function: pq-env-2-encoding
1264 Return the integer code representing the coding system in
1269 Compatibility note: This function did not exist prior to libpq-7.0
1270 and does not exist in a non-Mule XEmacs.
1272 - Function: pq-clear res
1273 Destroy a query result object by calling free() on it. RES a
1276 Note: The memory allocation systems of libpq and XEmacs are
1277 different. The XEmacs representation of a query result object
1278 will have both the XEmacs version and the libpq version freed at
1279 the next garbage collection when the object is no longer being
1280 referenced. Calling this function does not release the XEmacs
1281 object, it is still subject to the usual rules for Lisp objects.
1282 The printed representation of the XEmacs object will contain the
1283 string "DEAD" after this routine is called indicating that it is no
1284 longer useful for anything.
1286 - Function: pq-conn-defaults
1287 Return a data structure that represents the connection defaults.
1288 The data is returned as a list of lists, where each sublist
1289 contains info regarding a single option.