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.so
 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 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'.
 495
 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.
 499
 500 \1f
 501 File: lispref.info,  Node: XEmacs PostgreSQL libpq API,  Next: XEmacs PostgreSQL libpq Examples,  Prev: Building XEmacs with PostgreSQL support,  Up: PostgreSQL Support
 502
 503 XEmacs PostgreSQL libpq API
 504 ===========================
 505
 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.
 509
 510    This documentation assumes that the reader has knowledge of SQL, but
 511 requires no prior knowledge of libpq.
 512
 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.
 519
 520      (progn
 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")
 534        (pq-end-copy P))
 535           => nil
 536
 537 * Menu:
 538
 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::
 546
 547 \1f
 548 File: lispref.info,  Node: libpq Lisp Variables,  Next: libpq Lisp Symbols and DataTypes,  Prev: XEmacs PostgreSQL libpq API,  Up: XEmacs PostgreSQL libpq API
 549
 550 libpq Lisp Variables
 551 --------------------
 552
 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.
 559
 560  - Variable: pg:host
 561      Initialized from the PGHOST environment variable.  The default
 562      host to connect to.
 563
 564  - Variable: pg:user
 565      Initialized from the PGUSER environment variable.  The default
 566      database user name.
 567
 568  - Variable: pg:options
 569      Initialized from the PGOPTIONS environment variable.  Default
 570      additional server options.
 571
 572  - Variable: pg:port
 573      Initialized from the PGPORT environment variable.  The default TCP
 574      port to connect to.
 575
 576  - Variable: pg:tty
 577      Initialized from the PGTTY environment variable.  The default
 578      debugging TTY.
 579
 580      Compatibility note:  Debugging TTYs are turned off in the XEmacs
 581      Lisp binding.
 582
 583  - Variable: pg:database
 584      Initialized from the PGDATABASE environment variable.  The default
 585      database to connect to.
 586
 587  - Variable: pg:realm
 588      Initialized from the PGREALM environment variable.  The default
 589      Kerberos realm.
 590
 591  - Variable: pg:client-encoding
 592      Initialized from the PGCLIENTENCODING environment variable.  The
 593      default client encoding.
 594
 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.
 599
 600  - Variable: pg:authtype
 601      Initialized from the PGAUTHTYPE environment variable.  The default
 602      authentication scheme used.
 603
 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
 606      binding.
 607
 608  - Variable: pg:geqo
 609      Initialized from the PGGEQO environment variable.  Genetic
 610      optimizer options.
 611
 612  - Variable: pg:cost-index
 613      Initialized from the PGCOSTINDEX environment variable.  Cost index
 614      options.
 615
 616  - Variable: pg:cost-heap
 617      Initialized from the PGCOSTHEAP environment variable.  Cost heap
 618      options.
 619
 620  - Variable: pg:tz
 621      Initialized from the PGTZ environment variable.  Default timezone.
 622
 623  - Variable: pg:date-style
 624      Initialized from the PGDATESTYLE environment variable.  Default
 625      date style in returned date objects.
 626
 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.
 630
 631      Compatibility Note: This variable is not present in InfoDock.
 632
 633 \1f
 634 File: lispref.info,  Node: libpq Lisp Symbols and DataTypes,  Next: Synchronous Interface Functions,  Prev: libpq Lisp Variables,  Up: XEmacs PostgreSQL libpq API
 635
 636 libpq Lisp Symbols and Datatypes
 637 --------------------------------
 638
 639    The following set of symbols are used to represent the intermediate
 640 states involved in the asynchronous interface.
 641
 642  - Symbol: pgres::polling-failed
 643      Undocumented.  A fatal error has occurred during processing of an
 644      asynchronous operation.
 645
 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.
 649
 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.
 653
 654  - Symbol: pgres::polling-ok
 655      An asynchronous operation has successfully completed.
 656
 657  - Symbol: pgres::polling-active
 658      An intermediate status return during an asynchronous operation.
 659      One can call the poll function again immediately.
 660
 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
 664      following table.
 665     `pq::db'
 666           Database name
 667
 668     `pq::user'
 669           Database user name
 670
 671     `pq::pass'
 672           Database user's password
 673
 674     `pq::host'
 675           Hostname database server is running on
 676
 677     `pq::port'
 678           TCP port number used in the connection
 679
 680     `pq::tty'
 681           Debugging TTY
 682
 683           Compatibility note:  Debugging TTYs are not used in the
 684           XEmacs Lisp API.
 685
 686     `pq::options'
 687           Additional server options
 688
 689     `pq::status'
 690           Connection status.  Possible return values are shown in the
 691           following table.
 692          `pg::connection-ok'
 693                The normal, connected status.
 694
 695          `pg::connection-bad'
 696                The connection is not open and the PGconn object needs
 697                to be deleted by `pq-finish'.
 698
 699          `pg::connection-started'
 700                An asynchronous connection has been started, but is not
 701                yet complete.
 702
 703          `pg::connection-made'
 704                An asynchronous connect has been made, and there is data
 705                waiting to be sent.
 706
 707          `pg::connection-awaiting-response'
 708                Awaiting data from the backend during an asynchronous
 709                connection.
 710
 711          `pg::connection-auth-ok'
 712                Received authentication, waiting for the backend to
 713                start up.
 714
 715          `pg::connection-setenv'
 716                Negotiating environment during an asynchronous
 717                connection.
 718
 719     `pq::error-message'
 720           The last error message that was delivered to this connection.
 721
 722     `pq::backend-pid'
 723           The process ID of the backend database server.
 724
 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:
 728
 729      (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 730           => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
 731
 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:
 735
 736      (pq-exec P "CREATE TABLE a_new_table (i int);")
 737           => #<PGresult PGRES_COMMAND_OK - CREATE>
 738
 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
 741 like:
 742
 743      (progn
 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>
 749
 750    Lastly, when the underlying PGresult object has been deallocated
 751 directly by `pq-clear' the printed representation will look like:
 752
 753      (progn
 754        (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 755        (pq-clear R)
 756        R)
 757           => #<PGresult DEAD>
 758
 759    The following set of functions are accessors to various data in the
 760 PGresult object.
 761
 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.
 765     `pgres::empty-query'
 766           A query contained no text.  This is usually the result of a
 767           recoverable error, or a minor programming error.
 768
 769     `pgres::command-ok'
 770           A query command that doesn't return anything was executed
 771           properly by the backend.
 772
 773     `pgres::tuples-ok'
 774           A query command that returns tuples was executed properly by
 775           the backend.
 776
 777     `pgres::copy-out'
 778           Copy Out data transfer is in progress.
 779
 780     `pgres::copy-in'
 781           Copy In data transfer is in progress.
 782
 783     `pgres::bad-response'
 784           An unexpected response was received from the backend.
 785
 786     `pgres::nonfatal-error'
 787           Undocumented.  This value is returned when the libpq function
 788           `PQresultStatus' is called with a NULL pointer.
 789
 790     `pgres::fatal-error'
 791           Undocumented.  An error has occurred in processing the query
 792           and the operation was not completed.
 793
 794  - Function: pq-res-status result
 795      Return the query result status as a string, not a symbol.  RESULT
 796      is a PGresult object.
 797
 798           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 799                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
 800           (pq-res-status R)
 801                => "PGRES_TUPLES_OK"
 802
 803  - Function: pq-result-error-message result
 804      Return an error message generated by the query, if any.  RESULT is
 805      a PGresult object.
 806
 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 \"-\"
 811           "
 812
 813  - Function: pq-ntuples result
 814      Return the number of tuples in the query result.  RESULT is a
 815      PGresult object.
 816
 817           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 818                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
 819           (pq-ntuples R)
 820                => 5
 821
 822  - Function: pq-nfields result
 823      Return the number of fields in each tuple of the query result.
 824      RESULT is a PGresult object.
 825
 826           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 827                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
 828           (pq-nfields R)
 829                => 3
 830
 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.
 834
 835           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 836                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
 837           (pq-binary-tuples R)
 838                => nil
 839
 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.
 844
 845           (let (i l)
 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))
 850             l)
 851                => ("id" "shikona" "rank")
 852
 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>
 859           (pq-fnumber R "id")
 860                => 0
 861           (pq-fnumber R "Not a field")
 862                => -1
 863
 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
 867      number.
 868
 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.
 872
 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.
 877
 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.
 881
 882           (let (i l)
 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))
 887             l)
 888                => ((23 23) (25 25) (25 25))
 889
 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
 893      to fetch from.
 894
 895      Both tuples and fields are numbered from zero.
 896
 897           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 898                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
 899           (pq-get-value R 0 1)
 900                => "Musashimaru"
 901           (pq-get-value R 1 1)
 902                => "Dejima"
 903           (pq-get-value R 2 1)
 904                => "Musoyama"
 905
 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.
 910
 911           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 912                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
 913           (pq-get-length R 0 1)
 914                => 11
 915           (pq-get-length R 1 1)
 916                => 6
 917           (pq-get-length R 2 1)
 918                => 8
 919
 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.
 924
 925  - Function: pq-cmd-status result
 926      Return a summary string from the query.  RESULT is a PGresult
 927      object.
 928           (pq-exec P "INSERT INTO xemacs_test
 929                       VALUES (6, 'Wakanohana', 'Yokozuna');")
 930                => #<PGresult PGRES_COMMAND_OK[1] - INSERT 542086 1>
 931           (pq-cmd-status R)
 932                => "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>
 936           (pq-cmd-status R)
 937                => "UPDATE 1"
 938
 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.
 943
 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.
 948
 949           (setq R (pq-exec P "INSERT INTO xemacs_test VALUES
 950                               (7, 'Takanohana', 'Yokuzuna');"))
 951                => #<PGresult PGRES_COMMAND_OK[1] - INSERT 38688 1>
 952           (pq-cmd-tuples R)
 953                => "1"
 954           (setq R (pq-exec P "SELECT * from xemacs_test;"))
 955                => #<PGresult PGRES_TUPLES_OK[7] - SELECT>
 956           (pq-cmd-tuples R)
 957                => ""
 958           (setq R (pq-exec P "DELETE FROM xemacs_test
 959                               WHERE shikona LIKE '%hana';"))
 960                => #<PGresult PGRES_COMMAND_OK[2] - DELETE 2>
 961           (pq-cmd-tuples R)
 962                => "2"
 963
 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.
 968
 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>
 976           (pq-oid-value R)
 977                => 542089
 978           (setq R (pq-exec P "SELECT shikona FROM xemacs_test
 979                               WHERE rank='Maegashira';"))
 980                => #<PGresult PGRES_TUPLES_OK[2] - SELECT>
 981           (pq-oid-value R)
 982                => 0
 983
 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
 987      `pq-result-status'.
 988
 989      The caller is responsible for making sure the return value gets
 990      properly freed.
 991
 992 \1f
 993 File: lispref.info,  Node: Synchronous Interface Functions,  Next: Asynchronous Interface Functions,  Prev: libpq Lisp Symbols and DataTypes,  Up: XEmacs PostgreSQL libpq API
 994
 995 Synchronous Interface Functions
 996 -------------------------------
 997
 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.
1011
1012      Database connection objects which have been disconnected and will
1013      generate an immediate error if they are used look like:
1014             #<PGconn BAD>
1015      Bad connections can be reestablished with `pq-reset', or deleted
1016      entirely with `pq-finish'.
1017
1018      A database connection object that has been deleted looks like:
1019           (let ((P1 (pq-connectdb "")))
1020             (pq-finish P1)
1021             P1)
1022                => #<PGconn DEAD>
1023
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:
1030
1031           (let ((P (pq-connectiondb "")))
1032             (unwind-protect
1033                 (progn
1034                 (...)) ; access database here
1035               (pq-finish P)))
1036
1037      The following options are available in the options string:
1038     `authtype'
1039           Authentication type.  Same as PGAUTHTYPE.  This is no longer
1040           used.
1041
1042     `user'
1043           Database user name.  Same as PGUSER.
1044
1045     `password'
1046           Database password.
1047
1048     `dbname'
1049           Database name.  Same as PGDATABASE
1050
1051     `host'
1052           Symbolic hostname.  Same as PGHOST.
1053
1054     `hostaddr'
1055           Host address as four octets (eg. like 192.168.1.1).
1056
1057     `port'
1058           TCP port to connect to.  Same as PGPORT.
1059
1060     `tty'
1061           Debugging TTY.  Same as PGTTY.  This value is suppressed in
1062           the XEmacs Lisp API.
1063
1064     `options'
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.
1068
1069  - Function: pq-reset conn
1070      Reestablish database connection.  CONN A database connection
1071      object.
1072
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.
1076
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.
1084
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>
1088
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.
1096
1097  - Function: PQsetenv conn
1098      Synchronous transfer of environment variables to a backend CONN A
1099      database connection object.
1100
1101      Environment variable transfer is done as a normal part of database
1102      connection.
1103
1104      Compatibility note: This function was present but not documented
1105      in versions of libpq prior to 7.0.
1106
1107 \1f
1108 File: lispref.info,  Node: Asynchronous Interface Functions,  Next: Large Object Support,  Prev: Synchronous Interface Functions,  Up: XEmacs PostgreSQL libpq API
1109
1110 Asynchronous Interface Functions
1111 --------------------------------
1112
1113    Making command by command examples is too complex with the
1114 asynchronous interface functions.  See the examples section for
1115 complete calling sequences.
1116
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.
1121
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.
1126
1127  - Function: pq-is-busy conn
1128      Returns t if `pq-get-result' would block waiting for input.  CONN
1129      A database connection object.
1130
1131  - Function: pq-consume-input conn
1132      Consume any available input from the backend.  CONN A database
1133      connection object.
1134
1135      Nil is returned if anything bad happens.
1136
1137  - Function: pq-reset-start conn
1138      Reset connection to the backend asynchronously.  CONN A database
1139      connection object.
1140
1141  - Function: pq-reset-poll conn
1142      Poll an asynchronous reset for completion CONN A database
1143      connection object.
1144
1145  - Function: pq-reset-cancel conn
1146      Attempt to request cancellation of the current operation.  CONN A
1147      database connection object.
1148
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
1153      result as usual.
1154
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)
1159
1160  - Function: pq-get-result conn
1161      Retrieve an asynchronous result from a query.  CONN A database
1162      connection object.
1163
1164      NIL is returned when no more query work remains.
1165
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.
1171
1172  - Function: pq-is-nonblocking conn
1173      Return the blocking status of the database connection CONN A
1174      database connection object.
1175
1176  - Function: pq-flush conn
1177      Force the write buffer to be written (or at least try) CONN A
1178      database connection object.
1179
1180  - Function: PQsetenvStart conn
1181      Start asynchronously passing environment variables to a backend.
1182      CONN A database connection object.
1183
1184      Compatibility note: this function is only available with libpq-7.0.
1185
1186  - Function: PQsetenvPoll conn
1187      Check an asynchronous enviroment variables transfer for completion.
1188      CONN A database connection object.
1189
1190      Compatibility note: this function is only available with libpq-7.0.
1191
1192  - Function: PQsetenvAbort conn
1193      Attempt to terminate an asynchronous environment variables
1194      transfer.  CONN A database connection object.
1195
1196      Compatibility note: this function is only available with libpq-7.0.
1197
1198 \1f
1199 File: lispref.info,  Node: Large Object Support,  Next: Other libpq Functions,  Prev: Asynchronous Interface Functions,  Up: XEmacs PostgreSQL libpq API
1200
1201 Large Object Support
1202 --------------------
1203
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
1207
1208      On success, the object id is returned.
1209
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.
1214
1215 \1f
1216 File: lispref.info,  Node: Other libpq Functions,  Next: Unimplemented libpq Functions,  Prev: Large Object Support,  Up: XEmacs PostgreSQL libpq API
1217
1218 Other libpq Functions
1219 ---------------------
1220
1221  - Function: pq-finish conn
1222      Destroy a database connection object by calling free on it.  CONN
1223      a database connection object
1224
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
1230      occurred.
1231
1232      After calling this routine, the printed representation of the
1233      XEmacs wrapper object will contain the string "DEAD".
1234
1235  - Function: pq-client-encoding conn
1236      Return the client encoding as an integer code.  CONN a database
1237      connection object
1238
1239           (pq-client-encoding P)
1240                => 1
1241
1242      Compatibility note: This function did not exist prior to libpq-7.0
1243      and does not exist in a non-Mule XEmacs.
1244
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
1248
1249           (pq-set-client-encoding P "EUC_JP")
1250                => 0
1251
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")
1258             ...)
1259           (pq-finish P)
1260      Compatibility note: This function did not exist prior to libpq-7.0
1261      and does not exist in a non-Mule XEmacs.
1262
1263  - Function: pq-env-2-encoding
1264      Return the integer code representing the coding system in
1265      PGCLIENTENCODING.
1266
1267           (pq-env-2-encoding)
1268                => 0
1269      Compatibility note: This function did not exist prior to libpq-7.0
1270      and does not exist in a non-Mule XEmacs.
1271
1272  - Function: pq-clear res
1273      Destroy a query result object by calling free() on it.  RES a
1274      query result object
1275
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.
1285
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.
1290