info/lispref.info-42

   1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
   2 lispref/lispref.texi.
   3
   4 INFO-DIR-SECTION XEmacs Editor
   5 START-INFO-DIR-ENTRY
   6 * Lispref: (lispref).           XEmacs Lisp Reference Manual.
   7 END-INFO-DIR-ENTRY
   8
   9    Edition History:
  10
  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
  20
  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.
  24
  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.
  28
  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.
  33
  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.
  38
  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.
  45
  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.
  51
  52 \1f
  53 File: lispref.info,  Node: LDAP Variables,  Next: The High-Level LDAP API,  Prev: XEmacs LDAP API,  Up: XEmacs LDAP API
  54
  55 LDAP Variables
  56 --------------
  57
  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.
  61
  62  - Variable: ldap-default-port
  63      Default TCP port for LDAP connections.  Initialized from the LDAP
  64      library. Default value is 389.
  65
  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.
  70
  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
  77      properties:
  78     `binddn'
  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.
  81
  82     `passwd'
  83           The password to use for authentication.
  84
  85     `auth'
  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'.
  89
  90     `base'
  91           The base for the search. This may look like `cÿ, o¬me', see
  92           RFC 1779 for syntax details.
  93
  94     `scope'
  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.
  98
  99     `deref'
 100           The dereference policy is one of the symbols `never',
 101           `always', `search' or `find' and defines how aliases are
 102           dereferenced.
 103          `never'
 104                Aliases are never dereferenced
 105
 106          `always'
 107                Aliases are always dereferenced
 108
 109          `search'
 110                Aliases are dereferenced when searching
 111
 112          `find'
 113                Aliases are dereferenced when locating the base object
 114                for the search
 115
 116     `timelimit'
 117           The timeout limit for the connection in seconds.
 118
 119     `sizelimit'
 120           The maximum number of matches to return for searches
 121           performed on this connection.
 122
 123  - Variable: ldap-verbose
 124      If non-`nil', LDAP operations will echo progress messages.
 125      Defaults to `nil'.
 126
 127 \1f
 128 File: lispref.info,  Node: The High-Level LDAP API,  Next: The Low-Level LDAP API,  Prev: LDAP Variables,  Up: XEmacs LDAP API
 129
 130 The High-Level LDAP API
 131 -----------------------
 132
 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::.
 139
 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.
 147
 148  - Function: ldap-search-entries filter &optional host attributes
 149           attrsonly withdn
 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.
 161
 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.
 169
 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"
 182
 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.
 188
 189 \1f
 190 File: lispref.info,  Node: The Low-Level LDAP API,  Next: LDAP Internationalization,  Prev: The High-Level LDAP API,  Up: XEmacs LDAP API
 191
 192 The Low-Level LDAP API
 193 ----------------------
 194
 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::
 201
 202    Note that the former functions `ldap-*-internal' functions have been
 203 renamed in XEmacs 21.2
 204
 205 * Menu:
 206
 207 * The LDAP Lisp Object::
 208 * Opening and Closing a LDAP Connection::
 209 * Low-level Operations on a LDAP Server::
 210
 211 \1f
 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
 213
 214 The LDAP Lisp Object
 215 ....................
 216
 217    An internal built-in `ldap' lisp object represents a LDAP connection.
 218
 219  - Function: ldapp object
 220      This function returns non-`nil' if OBJECT is a `ldap' object.
 221
 222  - Function: ldap-host ldap
 223      Return the server host of the connection represented by LDAP
 224
 225  - Function: ldap-live-p ldap
 226      Return non-`nil' if LDAP is an active LDAP connection
 227
 228 \1f
 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
 230
 231 Opening and Closing a LDAP Connection
 232 .....................................
 233
 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
 237      in that list are:
 238     `port'
 239           The TCP port to use for the connection if different from
 240           `ldap-default-port' or the library builtin value
 241
 242     `auth'
 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'.
 246
 247     `binddn'
 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
 250           details.
 251
 252     `passwd'
 253           The password to use for authentication.
 254
 255     `deref'
 256           The dereference policy is one of the symbols `never',
 257           `always', `search' or `find' and defines how aliases are
 258           dereferenced.
 259          `never'
 260                Aliases are never dereferenced
 261
 262          `always'
 263                Aliases are always dereferenced
 264
 265          `search'
 266                Aliases are dereferenced when searching
 267
 268          `find'
 269                Aliases are dereferenced when locating the base object
 270                for the search The default is `never'.
 271
 272     `timelimit'
 273           The timeout limit for the connection in seconds.
 274
 275     `sizelimit'
 276           The maximum number of matches to return for searches
 277           performed on this connection.
 278
 279  - Function: ldap-close ldap
 280      Close the connection represented by LDAP
 281
 282 \1f
 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
 284
 285 Low-level Operations on a LDAP Server
 286 .....................................
 287
 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
 292 `ldap-close'.
 293
 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'.
 311
 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.
 317
 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
 327
 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
 331      the entry to delete
 332
 333 \1f
 334 File: lispref.info,  Node: LDAP Internationalization,  Prev: The Low-Level LDAP API,  Up: XEmacs LDAP API
 335
 336 LDAP Internationalization
 337 -------------------------
 338
 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
 344 place though.
 345
 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).
 351
 352 * Menu:
 353
 354 * LDAP Internationalization Variables::
 355 * Encoder/Decoder Functions::
 356
 357 \1f
 358 File: lispref.info,  Node: LDAP Internationalization Variables,  Next: Encoder/Decoder Functions,  Prev: LDAP Internationalization,  Up: LDAP Internationalization
 359
 360 LDAP Internationalization Variables
 361 ...................................
 362
 363  - Variable: ldap-ignore-attribute-codings
 364      If non-`nil', no encoding/decoding will be performed LDAP
 365      attribute values
 366
 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
 370      support for this.
 371
 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
 376
 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.
 383
 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.
 390
 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
 394
 395 \1f
 396 File: lispref.info,  Node: Encoder/Decoder Functions,  Prev: LDAP Internationalization Variables,  Up: LDAP Internationalization
 397
 398 Encoder/Decoder Functions
 399 .........................
 400
 401  - Function: ldap-encode-boolean bool
 402      A function that encodes an elisp boolean BOOL into a LDAP boolean
 403      string representation
 404
 405  - Function: ldap-decode-boolean str
 406      A function that decodes a LDAP boolean string representation STR
 407      into an elisp boolean
 408
 409  - Function: ldap-decode-string str
 410      Decode a string STR according to `ldap-coding-system'
 411
 412  - Function: ldap-encode-string str
 413      Encode a string STR according to `ldap-coding-system'
 414
 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
 418      rules for addresses
 419
 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
 423      rules for addresses
 424
 425 \1f
 426 File: lispref.info,  Node: Syntax of Search Filters,  Prev: XEmacs LDAP API,  Up: LDAP Support
 427
 428 Syntax of Search Filters
 429 ========================
 430
 431    LDAP search functions use RFC1558 syntax to describe the search
 432 filter.  In that syntax simple filters have the form:
 433
 434      (<attr> <filtertype> <value>)
 435
 436    `<attr>' is an attribute name such as `cn' for Common Name, `o' for
 437 Organization, etc...
 438
 439    `<value>' is the corresponding value.  This is generally an exact
 440 string but may also contain `*' characters as wildcards
 441
 442    `filtertype' is one `=' `~=', `<=', `>=' which respectively describe
 443 equality, approximate equality, inferiority and superiority.
 444
 445    Thus `(cn=John Smith)' matches all records having a canonical name
 446 equal to John Smith.
 447
 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.
 451
 452    Simple filters can be connected together with the logical operators
 453 `&', `|' and `!' which stand for the usual and, or and not operators.
 454
 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
 458 is `John'.
 459
 460 \1f
 461 File: lispref.info,  Node: PostgreSQL Support,  Next: Internationalization,  Prev: LDAP Support,  Up: Top
 462
 463 PostgreSQL Support
 464 ******************
 465
 466    XEmacs can be linked with PostgreSQL libpq run-time support to
 467 provide relational database access from Emacs Lisp code.
 468
 469 * Menu:
 470
 471 * Building XEmacs with PostgreSQL support::
 472 * XEmacs PostgreSQL libpq API::
 473 * XEmacs PostgreSQL libpq Examples::
 474
 475 \1f
 476 File: lispref.info,  Node: Building XEmacs with PostgreSQL support,  Next: XEmacs PostgreSQL libpq API,  Up: PostgreSQL Support
 477
 478 Building XEmacs with PostgreSQL support
 479 =======================================
 480
 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.
 484
 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.
 489
 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
 497 `--site-prefixes'.
 498
 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.
 502
 503 \1f
 504 File: lispref.info,  Node: XEmacs PostgreSQL libpq API,  Next: XEmacs PostgreSQL libpq Examples,  Prev: Building XEmacs with PostgreSQL support,  Up: PostgreSQL Support
 505
 506 XEmacs PostgreSQL libpq API
 507 ===========================
 508
 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.
 512
 513    This documentation assumes that the reader has knowledge of SQL, but
 514 requires no prior knowledge of libpq.
 515
 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.
 522
 523      (progn
 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")
 537        (pq-end-copy P))
 538           => nil
 539
 540 * Menu:
 541
 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::
 549
 550 \1f
 551 File: lispref.info,  Node: libpq Lisp Variables,  Next: libpq Lisp Symbols and DataTypes,  Prev: XEmacs PostgreSQL libpq API,  Up: XEmacs PostgreSQL libpq API
 552
 553 libpq Lisp Variables
 554 --------------------
 555
 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.
 562
 563  - Variable: pg:host
 564      Initialized from the PGHOST environment variable.  The default
 565      host to connect to.
 566
 567  - Variable: pg:user
 568      Initialized from the PGUSER environment variable.  The default
 569      database user name.
 570
 571  - Variable: pg:options
 572      Initialized from the PGOPTIONS environment variable.  Default
 573      additional server options.
 574
 575  - Variable: pg:port
 576      Initialized from the PGPORT environment variable.  The default TCP
 577      port to connect to.
 578
 579  - Variable: pg:tty
 580      Initialized from the PGTTY environment variable.  The default
 581      debugging TTY.
 582
 583      Compatibility note:  Debugging TTYs are turned off in the XEmacs
 584      Lisp binding.
 585
 586  - Variable: pg:database
 587      Initialized from the PGDATABASE environment variable.  The default
 588      database to connect to.
 589
 590  - Variable: pg:realm
 591      Initialized from the PGREALM environment variable.  The default
 592      Kerberos realm.
 593
 594  - Variable: pg:client-encoding
 595      Initialized from the PGCLIENTENCODING environment variable.  The
 596      default client encoding.
 597
 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.
 602
 603  - Variable: pg:authtype
 604      Initialized from the PGAUTHTYPE environment variable.  The default
 605      authentication scheme used.
 606
 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
 609      binding.
 610
 611  - Variable: pg:geqo
 612      Initialized from the PGGEQO environment variable.  Genetic
 613      optimizer options.
 614
 615  - Variable: pg:cost-index
 616      Initialized from the PGCOSTINDEX environment variable.  Cost index
 617      options.
 618
 619  - Variable: pg:cost-heap
 620      Initialized from the PGCOSTHEAP environment variable.  Cost heap
 621      options.
 622
 623  - Variable: pg:tz
 624      Initialized from the PGTZ environment variable.  Default timezone.
 625
 626  - Variable: pg:date-style
 627      Initialized from the PGDATESTYLE environment variable.  Default
 628      date style in returned date objects.
 629
 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.
 633
 634      Compatibility Note: This variable is not present in InfoDock.
 635
 636 \1f
 637 File: lispref.info,  Node: libpq Lisp Symbols and DataTypes,  Next: Synchronous Interface Functions,  Prev: libpq Lisp Variables,  Up: XEmacs PostgreSQL libpq API
 638
 639 libpq Lisp Symbols and Datatypes
 640 --------------------------------
 641
 642    The following set of symbols are used to represent the intermediate
 643 states involved in the asynchronous interface.
 644
 645  - Symbol: pgres::polling-failed
 646      Undocumented.  A fatal error has occurred during processing of an
 647      asynchronous operation.
 648
 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.
 652
 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.
 656
 657  - Symbol: pgres::polling-ok
 658      An asynchronous operation has successfully completed.
 659
 660  - Symbol: pgres::polling-active
 661      An intermediate status return during an asynchronous operation.
 662      One can call the poll function again immediately.
 663
 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
 667      following table.
 668     `pq::db'
 669           Database name
 670
 671     `pq::user'
 672           Database user name
 673
 674     `pq::pass'
 675           Database user's password
 676
 677     `pq::host'
 678           Hostname database server is running on
 679
 680     `pq::port'
 681           TCP port number used in the connection
 682
 683     `pq::tty'
 684           Debugging TTY
 685
 686           Compatibility note:  Debugging TTYs are not used in the
 687           XEmacs Lisp API.
 688
 689     `pq::options'
 690           Additional server options
 691
 692     `pq::status'
 693           Connection status.  Possible return values are shown in the
 694           following table.
 695          `pg::connection-ok'
 696                The normal, connected status.
 697
 698          `pg::connection-bad'
 699                The connection is not open and the PGconn object needs
 700                to be deleted by `pq-finish'.
 701
 702          `pg::connection-started'
 703                An asynchronous connection has been started, but is not
 704                yet complete.
 705
 706          `pg::connection-made'
 707                An asynchronous connect has been made, and there is data
 708                waiting to be sent.
 709
 710          `pg::connection-awaiting-response'
 711                Awaiting data from the backend during an asynchronous
 712                connection.
 713
 714          `pg::connection-auth-ok'
 715                Received authentication, waiting for the backend to
 716                start up.
 717
 718          `pg::connection-setenv'
 719                Negotiating environment during an asynchronous
 720                connection.
 721
 722     `pq::error-message'
 723           The last error message that was delivered to this connection.
 724
 725     `pq::backend-pid'
 726           The process ID of the backend database server.
 727
 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:
 731
 732      (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 733           => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
 734
 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:
 738
 739      (pq-exec P "CREATE TABLE a_new_table (i int);")
 740           => #<PGresult PGRES_COMMAND_OK - CREATE>
 741
 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
 744 like:
 745
 746      (progn
 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>
 752
 753    Lastly, when the underlying PGresult object has been deallocated
 754 directly by `pq-clear' the printed representation will look like:
 755
 756      (progn
 757        (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 758        (pq-clear R)
 759        R)
 760           => #<PGresult DEAD>
 761
 762    The following set of functions are accessors to various data in the
 763 PGresult object.
 764
 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.
 768     `pgres::empty-query'
 769           A query contained no text.  This is usually the result of a
 770           recoverable error, or a minor programming error.
 771
 772     `pgres::command-ok'
 773           A query command that doesn't return anything was executed
 774           properly by the backend.
 775
 776     `pgres::tuples-ok'
 777           A query command that returns tuples was executed properly by
 778           the backend.
 779
 780     `pgres::copy-out'
 781           Copy Out data transfer is in progress.
 782
 783     `pgres::copy-in'
 784           Copy In data transfer is in progress.
 785
 786     `pgres::bad-response'
 787           An unexpected response was received from the backend.
 788
 789     `pgres::nonfatal-error'
 790           Undocumented.  This value is returned when the libpq function
 791           `PQresultStatus' is called with a NULL pointer.
 792
 793     `pgres::fatal-error'
 794           Undocumented.  An error has occurred in processing the query
 795           and the operation was not completed.
 796
 797  - Function: pq-res-status result
 798      Return the query result status as a string, not a symbol.  RESULT
 799      is a PGresult object.
 800
 801           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 802                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
 803           (pq-res-status R)
 804                => "PGRES_TUPLES_OK"
 805
 806  - Function: pq-result-error-message result
 807      Return an error message generated by the query, if any.  RESULT is
 808      a PGresult object.
 809
 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 \"-\"
 814           "
 815
 816  - Function: pq-ntuples result
 817      Return the number of tuples in the query result.  RESULT is a
 818      PGresult object.
 819
 820           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 821                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
 822           (pq-ntuples R)
 823                => 5
 824
 825  - Function: pq-nfields result
 826      Return the number of fields in each tuple of the query result.
 827      RESULT is a PGresult object.
 828
 829           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 830                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
 831           (pq-nfields R)
 832                => 3
 833
 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.
 837
 838           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 839                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
 840           (pq-binary-tuples R)
 841                => nil
 842
 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.
 847
 848           (let (i l)
 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))
 853             l)
 854                => ("id" "shikona" "rank")
 855
 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>
 862           (pq-fnumber R "id")
 863                => 0
 864           (pq-fnumber R "Not a field")
 865                => -1
 866
 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
 870      number.
 871
 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.
 875
 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.
 880
 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.
 884
 885           (let (i l)
 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))
 890             l)
 891                => ((23 23) (25 25) (25 25))
 892
 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
 896      to fetch from.
 897
 898      Both tuples and fields are numbered from zero.
 899
 900           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 901                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
 902           (pq-get-value R 0 1)
 903                => "Musashimaru"
 904           (pq-get-value R 1 1)
 905                => "Dejima"
 906           (pq-get-value R 2 1)
 907                => "Musoyama"
 908
 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.
 913
 914           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 915                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
 916           (pq-get-length R 0 1)
 917                => 11
 918           (pq-get-length R 1 1)
 919                => 6
 920           (pq-get-length R 2 1)
 921                => 8
 922
 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.
 927
 928  - Function: pq-cmd-status result
 929      Return a summary string from the query.  RESULT is a PGresult
 930      object.
 931           (pq-exec P "INSERT INTO xemacs_test
 932                       VALUES (6, 'Wakanohana', 'Yokozuna');")
 933                => #<PGresult PGRES_COMMAND_OK[1] - INSERT 542086 1>
 934           (pq-cmd-status R)
 935                => "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>
 939           (pq-cmd-status R)
 940                => "UPDATE 1"
 941
 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.
 946
 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.
 951
 952           (setq R (pq-exec P "INSERT INTO xemacs_test VALUES
 953                               (7, 'Takanohana', 'Yokuzuna');"))
 954                => #<PGresult PGRES_COMMAND_OK[1] - INSERT 38688 1>
 955           (pq-cmd-tuples R)
 956                => "1"
 957           (setq R (pq-exec P "SELECT * from xemacs_test;"))
 958                => #<PGresult PGRES_TUPLES_OK[7] - SELECT>
 959           (pq-cmd-tuples R)
 960                => ""
 961           (setq R (pq-exec P "DELETE FROM xemacs_test
 962                               WHERE shikona LIKE '%hana';"))
 963                => #<PGresult PGRES_COMMAND_OK[2] - DELETE 2>
 964           (pq-cmd-tuples R)
 965                => "2"
 966
 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.
 971
 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>
 979           (pq-oid-value R)
 980                => 542089
 981           (setq R (pq-exec P "SELECT shikona FROM xemacs_test
 982                               WHERE rank='Maegashira';"))
 983                => #<PGresult PGRES_TUPLES_OK[2] - SELECT>
 984           (pq-oid-value R)
 985                => 0
 986
 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
 990      `pq-result-status'.
 991
 992      The caller is responsible for making sure the return value gets
 993      properly freed.
 994
 995 \1f
 996 File: lispref.info,  Node: Synchronous Interface Functions,  Next: Asynchronous Interface Functions,  Prev: libpq Lisp Symbols and DataTypes,  Up: XEmacs PostgreSQL libpq API
 997
 998 Synchronous Interface Functions
 999 -------------------------------
1000
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.
1014
1015      Database connection objects which have been disconnected and will
1016      generate an immediate error if they are used look like:
1017             #<PGconn BAD>
1018      Bad connections can be reestablished with `pq-reset', or deleted
1019      entirely with `pq-finish'.
1020
1021      A database connection object that has been deleted looks like:
1022           (let ((P1 (pq-connectdb "")))
1023             (pq-finish P1)
1024             P1)
1025                => #<PGconn DEAD>
1026
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:
1033
1034           (let ((P (pq-connectiondb "")))
1035             (unwind-protect
1036                 (progn
1037                 (...)) ; access database here
1038               (pq-finish P)))
1039
1040      The following options are available in the options string:
1041     `authtype'
1042           Authentication type.  Same as PGAUTHTYPE.  This is no longer
1043           used.
1044
1045     `user'
1046           Database user name.  Same as PGUSER.
1047
1048     `password'
1049           Database password.
1050
1051     `dbname'
1052           Database name.  Same as PGDATABASE
1053
1054     `host'
1055           Symbolic hostname.  Same as PGHOST.
1056
1057     `hostaddr'
1058           Host address as four octets (eg. like 192.168.1.1).
1059
1060     `port'
1061           TCP port to connect to.  Same as PGPORT.
1062
1063     `tty'
1064           Debugging TTY.  Same as PGTTY.  This value is suppressed in
1065           the XEmacs Lisp API.
1066
1067     `options'
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.
1071
1072  - Function: pq-reset conn
1073      Reestablish database connection.  CONN A database connection
1074      object.
1075
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.
1079
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.
1087
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>
1091
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.
1099
1100  - Function: PQsetenv conn
1101      Synchronous transfer of environment variables to a backend CONN A
1102      database connection object.
1103
1104      Environment variable transfer is done as a normal part of database
1105      connection.
1106
1107      Compatibility note: This function was present but not documented
1108      in versions of libpq prior to 7.0.
1109
1110 \1f
1111 File: lispref.info,  Node: Asynchronous Interface Functions,  Next: Large Object Support,  Prev: Synchronous Interface Functions,  Up: XEmacs PostgreSQL libpq API
1112
1113 Asynchronous Interface Functions
1114 --------------------------------
1115
1116    Making command by command examples is too complex with the
1117 asynchronous interface functions.  See the examples section for
1118 complete calling sequences.
1119
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.
1124
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.
1129
1130  - Function: pq-is-busy conn
1131      Returns t if `pq-get-result' would block waiting for input.  CONN
1132      A database connection object.
1133
1134  - Function: pq-consume-input conn
1135      Consume any available input from the backend.  CONN A database
1136      connection object.
1137
1138      Nil is returned if anything bad happens.
1139
1140  - Function: pq-reset-start conn
1141      Reset connection to the backend asynchronously.  CONN A database
1142      connection object.
1143
1144  - Function: pq-reset-poll conn
1145      Poll an asynchronous reset for completion CONN A database
1146      connection object.
1147
1148  - Function: pq-reset-cancel conn
1149      Attempt to request cancellation of the current operation.  CONN A
1150      database connection object.
1151
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
1156      result as usual.
1157
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)
1162
1163  - Function: pq-get-result conn
1164      Retrieve an asynchronous result from a query.  CONN A database
1165      connection object.
1166
1167      NIL is returned when no more query work remains.
1168
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.
1174
1175  - Function: pq-is-nonblocking conn
1176      Return the blocking status of the database connection CONN A
1177      database connection object.
1178
1179  - Function: pq-flush conn
1180      Force the write buffer to be written (or at least try) CONN A
1181      database connection object.
1182
1183  - Function: PQsetenvStart conn
1184      Start asynchronously passing environment variables to a backend.
1185      CONN A database connection object.
1186
1187      Compatibility note: this function is only available with libpq-7.0.
1188
1189  - Function: PQsetenvPoll conn
1190      Check an asynchronous environment variables transfer for
1191      completion.  CONN A database connection object.
1192
1193      Compatibility note: this function is only available with libpq-7.0.
1194
1195  - Function: PQsetenvAbort conn
1196      Attempt to terminate an asynchronous environment variables
1197      transfer.  CONN A database connection object.
1198
1199      Compatibility note: this function is only available with libpq-7.0.
1200
1201 \1f
1202 File: lispref.info,  Node: Large Object Support,  Next: Other libpq Functions,  Prev: Asynchronous Interface Functions,  Up: XEmacs PostgreSQL libpq API
1203
1204 Large Object Support
1205 --------------------
1206
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
1210
1211      On success, the object id is returned.
1212
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.
1217
1218 \1f
1219 File: lispref.info,  Node: Other libpq Functions,  Next: Unimplemented libpq Functions,  Prev: Large Object Support,  Up: XEmacs PostgreSQL libpq API
1220
1221 Other libpq Functions
1222 ---------------------
1223
1224  - Function: pq-finish conn
1225      Destroy a database connection object by calling free on it.  CONN
1226      a database connection object
1227
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
1233      occurred.
1234
1235      After calling this routine, the printed representation of the
1236      XEmacs wrapper object will contain the string "DEAD".
1237
1238  - Function: pq-client-encoding conn
1239      Return the client encoding as an integer code.  CONN a database
1240      connection object
1241
1242           (pq-client-encoding P)
1243                => 1
1244
1245      Compatibility note: This function did not exist prior to libpq-7.0
1246      and does not exist in a non-Mule XEmacs.
1247
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
1251
1252           (pq-set-client-encoding P "EUC_JP")
1253                => 0
1254
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")
1261             ...)
1262           (pq-finish P)
1263      Compatibility note: This function did not exist prior to libpq-7.0
1264      and does not exist in a non-Mule XEmacs.
1265
1266  - Function: pq-env-2-encoding
1267      Return the integer code representing the coding system in
1268      PGCLIENTENCODING.
1269
1270           (pq-env-2-encoding)
1271                => 0
1272      Compatibility note: This function did not exist prior to libpq-7.0
1273      and does not exist in a non-Mule XEmacs.
1274
1275  - Function: pq-clear res
1276      Destroy a query result object by calling free() on it.  RES a
1277      query result object
1278
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.
1288
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.
1293