info/lispref.info-43

   1 This is ../info/lispref.info, produced by makeinfo version 4.0b 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: libpq Lisp Symbols and DataTypes,  Next: Synchronous Interface Functions,  Prev: libpq Lisp Variables,  Up: XEmacs PostgreSQL libpq API
  54
  55 libpq Lisp Symbols and Datatypes
  56 --------------------------------
  57
  58    The following set of symbols are used to represent the intermediate
  59 states involved in the asynchronous interface.
  60
  61  - Symbol: pgres::polling-failed
  62      Undocumented.  A fatal error has occurred during processing of an
  63      asynchronous operation.
  64
  65  - Symbol: pgres::polling-reading
  66      An intermediate status return during an asynchronous operation.  It
  67      indicates that one may use `select' before polling again.
  68
  69  - Symbol: pgres::polling-writing
  70      An intermediate status return during an asynchronous operation.  It
  71      indicates that one may use `select' before polling again.
  72
  73  - Symbol: pgres::polling-ok
  74      An asynchronous operation has successfully completed.
  75
  76  - Symbol: pgres::polling-active
  77      An intermediate status return during an asynchronous operation.
  78      One can call the poll function again immediately.
  79
  80  - Function: pq-pgconn conn field
  81      CONN A database connection object.  FIELD A symbol indicating
  82      which field of PGconn to fetch.  Possible values are shown in the
  83      following table.
  84     `pq::db'
  85           Database name
  86
  87     `pq::user'
  88           Database user name
  89
  90     `pq::pass'
  91           Database user's password
  92
  93     `pq::host'
  94           Hostname database server is running on
  95
  96     `pq::port'
  97           TCP port number used in the connection
  98
  99     `pq::tty'
 100           Debugging TTY
 101
 102           Compatibility note:  Debugging TTYs are not used in the
 103           XEmacs Lisp API.
 104
 105     `pq::options'
 106           Additional server options
 107
 108     `pq::status'
 109           Connection status.  Possible return values are shown in the
 110           following table.
 111          `pg::connection-ok'
 112                The normal, connected status.
 113
 114          `pg::connection-bad'
 115                The connection is not open and the PGconn object needs
 116                to be deleted by `pq-finish'.
 117
 118          `pg::connection-started'
 119                An asynchronous connection has been started, but is not
 120                yet complete.
 121
 122          `pg::connection-made'
 123                An asynchronous connect has been made, and there is data
 124                waiting to be sent.
 125
 126          `pg::connection-awaiting-response'
 127                Awaiting data from the backend during an asynchronous
 128                connection.
 129
 130          `pg::connection-auth-ok'
 131                Received authentication, waiting for the backend to
 132                start up.
 133
 134          `pg::connection-setenv'
 135                Negotiating environment during an asynchronous
 136                connection.
 137
 138     `pq::error-message'
 139           The last error message that was delivered to this connection.
 140
 141     `pq::backend-pid'
 142           The process ID of the backend database server.
 143
 144    The `PGresult' object is used by libpq to encapsulate the results of
 145 queries.  The printed representation takes on four forms.  When the
 146 PGresult object contains tuples from an SQL `SELECT' it will look like:
 147
 148      (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 149           => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
 150
 151    The number in brackets indicates how many rows of data are available.
 152 When the PGresult object is the result of a command query that doesn't
 153 return anything, it will look like:
 154
 155      (pq-exec P "CREATE TABLE a_new_table (i int);")
 156           => #<PGresult PGRES_COMMAND_OK - CREATE>
 157
 158    When either the query is a command-type query that can affect a
 159 number of different rows, but doesn't return any of them it will look
 160 like:
 161
 162      (progn
 163        (pq-exec P "INSERT INTO a_new_table VALUES (1);")
 164        (pq-exec P "INSERT INTO a_new_table VALUES (2);")
 165        (pq-exec P "INSERT INTO a_new_table VALUES (3);")
 166        (setq R (pq-exec P "DELETE FROM a_new_table;")))
 167           => #<PGresult PGRES_COMMAND_OK[3] - DELETE 3>
 168
 169    Lastly, when the underlying PGresult object has been deallocated
 170 directly by `pq-clear' the printed representation will look like:
 171
 172      (progn
 173        (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 174        (pq-clear R)
 175        R)
 176           => #<PGresult DEAD>
 177
 178    The following set of functions are accessors to various data in the
 179 PGresult object.
 180
 181  - Function: pq-result-status result
 182      Return status of a query result.  RESULT is a PGresult object.
 183      The return value is one of the symbols in the following table.
 184     `pgres::empty-query'
 185           A query contained no text.  This is usually the result of a
 186           recoverable error, or a minor programming error.
 187
 188     `pgres::command-ok'
 189           A query command that doesn't return anything was executed
 190           properly by the backend.
 191
 192     `pgres::tuples-ok'
 193           A query command that returns tuples was executed properly by
 194           the backend.
 195
 196     `pgres::copy-out'
 197           Copy Out data transfer is in progress.
 198
 199     `pgres::copy-in'
 200           Copy In data transfer is in progress.
 201
 202     `pgres::bad-response'
 203           An unexpected response was received from the backend.
 204
 205     `pgres::nonfatal-error'
 206           Undocumented.  This value is returned when the libpq function
 207           `PQresultStatus' is called with a NULL pointer.
 208
 209     `pgres::fatal-error'
 210           Undocumented.  An error has occurred in processing the query
 211           and the operation was not completed.
 212
 213  - Function: pq-res-status result
 214      Return the query result status as a string, not a symbol.  RESULT
 215      is a PGresult object.
 216
 217           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 218                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
 219           (pq-res-status R)
 220                => "PGRES_TUPLES_OK"
 221
 222  - Function: pq-result-error-message result
 223      Return an error message generated by the query, if any.  RESULT is
 224      a PGresult object.
 225
 226           (setq R (pq-exec P "SELECT * FROM xemacs-test;"))
 227                => <A fatal error is signaled in the echo area>
 228           (pq-result-error-message R)
 229                => "ERROR:  parser: parse error at or near \"-\"
 230           "
 231
 232  - Function: pq-ntuples result
 233      Return the number of tuples in the query result.  RESULT is a
 234      PGresult object.
 235
 236           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 237                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
 238           (pq-ntuples R)
 239                => 5
 240
 241  - Function: pq-nfields result
 242      Return the number of fields in each tuple of the query result.
 243      RESULT is a PGresult object.
 244
 245           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 246                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
 247           (pq-nfields R)
 248                => 3
 249
 250  - Function: pq-binary-tuples result
 251      Returns t if binary tuples are present in the results, nil
 252      otherwise.  RESULT is a PGresult object.
 253
 254           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 255                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
 256           (pq-binary-tuples R)
 257                => nil
 258
 259  - Function: pq-fname result field-index
 260      Returns the name of a specific field.  RESULT is a PGresult object.
 261      FIELD-INDEX is the number of the column to select from.  The first
 262      column is number zero.
 263
 264           (let (i l)
 265             (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 266             (setq i (pq-nfields R))
 267             (while (>= (decf i) 0)
 268               (push (pq-fname R i) l))
 269             l)
 270                => ("id" "shikona" "rank")
 271
 272  - Function: pq-fnumber result field-name
 273      Return the field number corresponding to the given field name.  -1
 274      is returned on a bad field name.  RESULT is a PGresult object.
 275      FIELD-NAME is a string representing the field name to find.
 276           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 277                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
 278           (pq-fnumber R "id")
 279                => 0
 280           (pq-fnumber R "Not a field")
 281                => -1
 282
 283  - Function: pq-ftype result field-num
 284      Return an integer code representing the data type of the specified
 285      column.  RESULT is a PGresult object.  FIELD-NUM is the field
 286      number.
 287
 288      The return value of this function is the Object ID (Oid) in the
 289      database of the type.  Further queries need to be made to various
 290      system tables in order to convert this value into something useful.
 291
 292  - Function: pq-fmod result field-num
 293      Return the type modifier code associated with a field.  Field
 294      numbers start at zero.  RESULT is a PGresult object.  FIELD-INDEX
 295      selects which field to use.
 296
 297  - Function: pq-fsize result field-index
 298      Return size of the given field.  RESULT is a PGresult object.
 299      FIELD-INDEX selects which field to use.
 300
 301           (let (i l)
 302             (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 303             (setq i (pq-nfields R))
 304             (while (>= (decf i) 0)
 305               (push (list (pq-ftype R i) (pq-fsize R i)) l))
 306             l)
 307                => ((23 23) (25 25) (25 25))
 308
 309  - Function: pq-get-value result tup-num field-num
 310      Retrieve a return value.  RESULT is a PGresult object.  TUP-NUM
 311      selects which tuple to fetch from.  FIELD-NUM selects which field
 312      to fetch from.
 313
 314      Both tuples and fields are numbered from zero.
 315
 316           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 317                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
 318           (pq-get-value R 0 1)
 319                => "Musashimaru"
 320           (pq-get-value R 1 1)
 321                => "Dejima"
 322           (pq-get-value R 2 1)
 323                => "Musoyama"
 324
 325  - Function: pq-get-length result tup-num field-num
 326      Return the length of a specific value.  RESULT is a PGresult
 327      object.  TUP-NUM selects which tuple to fetch from.  FIELD-NUM
 328      selects which field to fetch from.
 329
 330           (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
 331                => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
 332           (pq-get-length R 0 1)
 333                => 11
 334           (pq-get-length R 1 1)
 335                => 6
 336           (pq-get-length R 2 1)
 337                => 8
 338
 339  - Function: pq-get-is-null result tup-num field-num
 340      Return t if the specific value is the SQL NULL.  RESULT is a
 341      PGresult object.  TUP-NUM selects which tuple to fetch from.
 342      FIELD-NUM selects which field to fetch from.
 343
 344  - Function: pq-cmd-status result
 345      Return a summary string from the query.  RESULT is a PGresult
 346      object.
 347           (pq-exec P "INSERT INTO xemacs_test
 348                       VALUES (6, 'Wakanohana', 'Yokozuna');")
 349                => #<PGresult PGRES_COMMAND_OK[1] - INSERT 542086 1>
 350           (pq-cmd-status R)
 351                => "INSERT 542086 1"
 352           (setq R (pq-exec P "UPDATE xemacs_test SET rank='retired'
 353                               WHERE shikona='Wakanohana';"))
 354                => #<PGresult PGRES_COMMAND_OK[1] - UPDATE 1>
 355           (pq-cmd-status R)
 356                => "UPDATE 1"
 357
 358      Note that the first number returned from an insertion, like in the
 359      example, is an object ID number and will almost certainly vary from
 360      system to system since object ID numbers in Postgres must be unique
 361      across all databases.
 362
 363  - Function: pq-cmd-tuples result
 364      Return the number of tuples if the last command was an
 365      INSERT/UPDATE/DELETE.  If the last command was something else, the
 366      empty string is returned.  RESULT is a PGresult object.
 367
 368           (setq R (pq-exec P "INSERT INTO xemacs_test VALUES
 369                               (7, 'Takanohana', 'Yokuzuna');"))
 370                => #<PGresult PGRES_COMMAND_OK[1] - INSERT 38688 1>
 371           (pq-cmd-tuples R)
 372                => "1"
 373           (setq R (pq-exec P "SELECT * from xemacs_test;"))
 374                => #<PGresult PGRES_TUPLES_OK[7] - SELECT>
 375           (pq-cmd-tuples R)
 376                => ""
 377           (setq R (pq-exec P "DELETE FROM xemacs_test
 378                               WHERE shikona LIKE '%hana';"))
 379                => #<PGresult PGRES_COMMAND_OK[2] - DELETE 2>
 380           (pq-cmd-tuples R)
 381                => "2"
 382
 383  - Function: pq-oid-value result
 384      Return the object id of the insertion if the last command was an
 385      INSERT.  0 is returned if the last command was not an insertion.
 386      RESULT is a PGresult object.
 387
 388      In the first example, the numbers you will see on your local
 389      system will almost certainly be different, however the second
 390      number from the right in the unprintable PGresult object and the
 391      number returned by `pq-oid-value' should match.
 392           (setq R (pq-exec P "INSERT INTO xemacs_test VALUES
 393                               (8, 'Terao', 'Maegashira');"))
 394                => #<PGresult PGRES_COMMAND_OK[1] - INSERT 542089 1>
 395           (pq-oid-value R)
 396                => 542089
 397           (setq R (pq-exec P "SELECT shikona FROM xemacs_test
 398                               WHERE rank='Maegashira';"))
 399                => #<PGresult PGRES_TUPLES_OK[2] - SELECT>
 400           (pq-oid-value R)
 401                => 0
 402
 403  - Function: pq-make-empty-pgresult conn status
 404      Create an empty pgresult with the given status.  CONN a database
 405      connection object STATUS a value that can be returned by
 406      `pq-result-status'.
 407
 408      The caller is responsible for making sure the return value gets
 409      properly freed.
 410
 411 \1f
 412 File: lispref.info,  Node: Synchronous Interface Functions,  Next: Asynchronous Interface Functions,  Prev: libpq Lisp Symbols and DataTypes,  Up: XEmacs PostgreSQL libpq API
 413
 414 Synchronous Interface Functions
 415 -------------------------------
 416
 417  - Function: pq-connectdb conninfo
 418      Establish a (synchronous) database connection.  CONNINFO A string
 419      of blank separated options.  Options are of the form "OPTION =
 420      VALUE".  If VALUE contains blanks, it must be single quoted.
 421      Blanks around the equal sign are optional.  Multiple option
 422      assignments are blank separated.
 423           (pq-connectdb "dbname=japanese port = 25432")
 424                => #<PGconn localhost:25432 steve/japanese>
 425      The printed representation of a database connection object has four
 426      fields.  The first field is the hostname where the database server
 427      is running (in this case localhost), the second field is the port
 428      number, the third field is the database user name, and the fourth
 429      field is the name of the database.
 430
 431      Database connection objects which have been disconnected and will
 432      generate an immediate error if they are used look like:
 433             #<PGconn BAD>
 434      Bad connections can be reestablished with `pq-reset', or deleted
 435      entirely with `pq-finish'.
 436
 437      A database connection object that has been deleted looks like:
 438           (let ((P1 (pq-connectdb "")))
 439             (pq-finish P1)
 440             P1)
 441                => #<PGconn DEAD>
 442
 443      Note that database connection objects are the most heavy weight
 444      objects in XEmacs Lisp at this writing, usually representing as
 445      much as several megabytes of virtual memory on the machine the
 446      database server is running on.  It is wisest to explicitly delete
 447      them when you are finished with them, rather than letting garbage
 448      collection do it.  An example idiom is:
 449
 450           (let ((P (pq-connectiondb "")))
 451             (unwind-protect
 452                 (progn
 453                 (...)) ; access database here
 454               (pq-finish P)))
 455
 456      The following options are available in the options string:
 457     `authtype'
 458           Authentication type.  Same as PGAUTHTYPE.  This is no longer
 459           used.
 460
 461     `user'
 462           Database user name.  Same as PGUSER.
 463
 464     `password'
 465           Database password.
 466
 467     `dbname'
 468           Database name.  Same as PGDATABASE
 469
 470     `host'
 471           Symbolic hostname.  Same as PGHOST.
 472
 473     `hostaddr'
 474           Host address as four octets (eg. like 192.168.1.1).
 475
 476     `port'
 477           TCP port to connect to.  Same as PGPORT.
 478
 479     `tty'
 480           Debugging TTY.  Same as PGTTY.  This value is suppressed in
 481           the XEmacs Lisp API.
 482
 483     `options'
 484           Extra backend database options.  Same as PGOPTIONS.  A
 485      database connection object is returned regardless of whether a
 486      connection was established or not.
 487
 488  - Function: pq-reset conn
 489      Reestablish database connection.  CONN A database connection
 490      object.
 491
 492      This function reestablishes a database connection using the
 493      original connection parameters.  This is useful if something has
 494      happened to the TCP link and it has become broken.
 495
 496  - Function: pq-exec conn query
 497      Make a synchronous database query.  CONN A database connection
 498      object.  QUERY A string containing an SQL query.  A PGresult
 499      object is returned, which in turn may be queried by its many
 500      accessor functions to retrieve state out of it.  If the query
 501      string contains multiple SQL commands, only results from the final
 502      command are returned.
 503
 504           (setq R (pq-exec P "SELECT * FROM xemacs_test;
 505           DELETE FROM xemacs_test WHERE id=8;"))
 506                => #<PGresult PGRES_COMMAND_OK[1] - DELETE 1>
 507
 508  - Function: pq-notifies conn
 509      Return the latest async notification that has not yet been handled.
 510      CONN A database connection object.  If there has been a
 511      notification, then a list of two elements will be returned.  The
 512      first element contains the relation name being notified, the second
 513      element contains the backend process ID number.  nil is returned
 514      if there aren't any notifications to process.
 515
 516  - Function: PQsetenv conn
 517      Synchronous transfer of environment variables to a backend CONN A
 518      database connection object.
 519
 520      Environment variable transfer is done as a normal part of database
 521      connection.
 522
 523      Compatibility note: This function was present but not documented
 524      in versions of libpq prior to 7.0.
 525
 526 \1f
 527 File: lispref.info,  Node: Asynchronous Interface Functions,  Next: Large Object Support,  Prev: Synchronous Interface Functions,  Up: XEmacs PostgreSQL libpq API
 528
 529 Asynchronous Interface Functions
 530 --------------------------------
 531
 532    Making command by command examples is too complex with the
 533 asynchronous interface functions.  See the examples section for
 534 complete calling sequences.
 535
 536  - Function: pq-connect-start conninfo
 537      Begin establishing an asynchronous database connection.  CONNINFO
 538      A string containing the connection options.  See the documentation
 539      of `pq-connectdb' for a listing of all the available flags.
 540
 541  - Function: pq-connect-poll conn
 542      An intermediate function to be called during an asynchronous
 543      database connection.  CONN A database connection object.  The
 544      result codes are documented in a previous section.
 545
 546  - Function: pq-is-busy conn
 547      Returns t if `pq-get-result' would block waiting for input.  CONN
 548      A database connection object.
 549
 550  - Function: pq-consume-input conn
 551      Consume any available input from the backend.  CONN A database
 552      connection object.
 553
 554      Nil is returned if anything bad happens.
 555
 556  - Function: pq-reset-start conn
 557      Reset connection to the backend asynchronously.  CONN A database
 558      connection object.
 559
 560  - Function: pq-reset-poll conn
 561      Poll an asynchronous reset for completion CONN A database
 562      connection object.
 563
 564  - Function: pq-reset-cancel conn
 565      Attempt to request cancellation of the current operation.  CONN A
 566      database connection object.
 567
 568      The return value is t if the cancel request was successfully
 569      dispatched, nil if not (in which case conn->errorMessage is set).
 570      Note: successful dispatch is no guarantee that there will be any
 571      effect at the backend.  The application must read the operation
 572      result as usual.
 573
 574  - Function: pq-send-query conn query
 575      Submit a query to Postgres and don't wait for the result.  CONN A
 576      database connection object.  Returns: t if successfully submitted
 577             nil if error (conn->errorMessage is set)
 578
 579  - Function: pq-get-result conn
 580      Retrieve an asynchronous result from a query.  CONN A database
 581      connection object.
 582
 583      `nil' is returned when no more query work remains.
 584
 585  - Function: pq-set-nonblocking conn arg
 586      Sets the PGconn's database connection non-blocking if the arg is
 587      TRUE or makes it non-blocking if the arg is FALSE, this will not
 588      protect you from PQexec(), you'll only be safe when using the
 589      non-blocking API.  CONN A database connection object.
 590
 591  - Function: pq-is-nonblocking conn
 592      Return the blocking status of the database connection CONN A
 593      database connection object.
 594
 595  - Function: pq-flush conn
 596      Force the write buffer to be written (or at least try) CONN A
 597      database connection object.
 598
 599  - Function: PQsetenvStart conn
 600      Start asynchronously passing environment variables to a backend.
 601      CONN A database connection object.
 602
 603      Compatibility note: this function is only available with libpq-7.0.
 604
 605  - Function: PQsetenvPoll conn
 606      Check an asynchronous environment variables transfer for
 607      completion.  CONN A database connection object.
 608
 609      Compatibility note: this function is only available with libpq-7.0.
 610
 611  - Function: PQsetenvAbort conn
 612      Attempt to terminate an asynchronous environment variables
 613      transfer.  CONN A database connection object.
 614
 615      Compatibility note: this function is only available with libpq-7.0.
 616
 617 \1f
 618 File: lispref.info,  Node: Large Object Support,  Next: Other libpq Functions,  Prev: Asynchronous Interface Functions,  Up: XEmacs PostgreSQL libpq API
 619
 620 Large Object Support
 621 --------------------
 622
 623  - Function: pq-lo-import conn filename
 624      Import a file as a large object into the database.  CONN a
 625      database connection object FILENAME filename to import
 626
 627      On success, the object id is returned.
 628
 629  - Function: pq-lo-export conn oid filename
 630      Copy a large object in the database into a file.  CONN a database
 631      connection object.  OID object id number of a large object.
 632      FILENAME filename to export to.
 633
 634 \1f
 635 File: lispref.info,  Node: Other libpq Functions,  Next: Unimplemented libpq Functions,  Prev: Large Object Support,  Up: XEmacs PostgreSQL libpq API
 636
 637 Other libpq Functions
 638 ---------------------
 639
 640  - Function: pq-finish conn
 641      Destroy a database connection object by calling free on it.  CONN
 642      a database connection object
 643
 644      It is possible to not call this routine because the usual XEmacs
 645      garbage collection mechanism will call the underlying libpq
 646      routine whenever it is releasing stale `PGconn' objects.  However,
 647      this routine is useful in `unwind-protect' clauses to make
 648      connections go away quickly when unrecoverable errors have
 649      occurred.
 650
 651      After calling this routine, the printed representation of the
 652      XEmacs wrapper object will contain the string "DEAD".
 653
 654  - Function: pq-client-encoding conn
 655      Return the client encoding as an integer code.  CONN a database
 656      connection object
 657
 658           (pq-client-encoding P)
 659                => 1
 660
 661      Compatibility note: This function did not exist prior to libpq-7.0
 662      and does not exist in a non-Mule XEmacs.
 663
 664  - Function: pq-set-client-encoding conn encoding
 665      Set client coding system.  CONN a database connection object
 666      ENCODING a string representing the desired coding system
 667
 668           (pq-set-client-encoding P "EUC_JP")
 669                => 0
 670
 671      The current idiom for ensuring proper coding system conversion is
 672      the following (illustrated for EUC Japanese encoding):
 673           (setq P (pq-connectdb "..."))
 674           (let ((file-name-coding-system 'euc-jp)
 675                 (pg-coding-system 'euc-jp))
 676             (pq-set-client-encoding "EUC_JP")
 677             ...)
 678           (pq-finish P)
 679      Compatibility note: This function did not exist prior to libpq-7.0
 680      and does not exist in a non-Mule XEmacs.
 681
 682  - Function: pq-env-2-encoding
 683      Return the integer code representing the coding system in
 684      PGCLIENTENCODING.
 685
 686           (pq-env-2-encoding)
 687                => 0
 688      Compatibility note: This function did not exist prior to libpq-7.0
 689      and does not exist in a non-Mule XEmacs.
 690
 691  - Function: pq-clear res
 692      Destroy a query result object by calling free() on it.  RES a
 693      query result object
 694
 695      Note:  The memory allocation systems of libpq and XEmacs are
 696      different.  The XEmacs representation of a query result object
 697      will have both the XEmacs version and the libpq version freed at
 698      the next garbage collection when the object is no longer being
 699      referenced.  Calling this function does not release the XEmacs
 700      object, it is still subject to the usual rules for Lisp objects.
 701      The printed representation of the XEmacs object will contain the
 702      string "DEAD" after this routine is called indicating that it is no
 703      longer useful for anything.
 704
 705  - Function: pq-conn-defaults
 706      Return a data structure that represents the connection defaults.
 707      The data is returned as a list of lists, where each sublist
 708      contains info regarding a single option.
 709
 710 \1f
 711 File: lispref.info,  Node: Unimplemented libpq Functions,  Prev: Other libpq Functions,  Up: XEmacs PostgreSQL libpq API
 712
 713 Unimplemented libpq Functions
 714 -----------------------------
 715
 716  - Unimplemented Function: PGconn *PQsetdbLogin (char *pghost, char
 717           *pgport, char *pgoptions, char *pgtty, char *dbName, char
 718           *login, char *pwd)
 719      Synchronous database connection.  PGHOST is the hostname of the
 720      PostgreSQL backend to connect to.  PGPORT is the TCP port number
 721      to use.  PGOPTIONS specifies other backend options.  PGTTY
 722      specifies the debugging tty to use.  DBNAME specifies the database
 723      name to use.  LOGIN specifies the database user name.  PWD
 724      specifies the database user's password.
 725
 726      This routine is deprecated as of libpq-7.0, and its functionality
 727      can be replaced by external Lisp code if needed.
 728
 729  - Unimplemented Function: PGconn *PQsetdb (char *pghost, char *pgport,
 730           char *pgoptions, char *pgtty, char *dbName)
 731      Synchronous database connection.  PGHOST is the hostname of the
 732      PostgreSQL backend to connect to.  PGPORT is the TCP port number
 733      to use.  PGOPTIONS specifies other backend options.  PGTTY
 734      specifies the debugging tty to use.  DBNAME specifies the database
 735      name to use.
 736
 737      This routine was deprecated in libpq-6.5.
 738
 739  - Unimplemented Function: int PQsocket (PGconn *conn)
 740      Return socket file descriptor to a backend database process.  CONN
 741      database connection object.
 742
 743  - Unimplemented Function: void PQprint (FILE *fout, PGresult *res,
 744           PGprintOpt *ps)
 745      Print out the results of a query to a designated C stream.  FOUT C
 746      stream to print to RES the query result object to print PS the
 747      print options structure.
 748
 749      This routine is deprecated as of libpq-7.0 and cannot be sensibly
 750      exported to XEmacs Lisp.
 751
 752  - Unimplemented Function: void PQdisplayTuples (PGresult *res, FILE
 753           *fp, int fillAlign, char *fieldSep, int printHeader, int
 754           quiet)
 755      RES query result object to print FP C stream to print to FILLALIGN
 756      pad the fields with spaces FIELDSEP field separator PRINTHEADER
 757      display headers?  QUIET
 758
 759      This routine was deprecated in libpq-6.5.
 760
 761  - Unimplemented Function: void PQprintTuples (PGresult *res, FILE
 762           *fout, int printAttName, int terseOutput, int width)
 763      RES query result object to print FOUT C stream to print to
 764      PRINTATTNAME print attribute names TERSEOUTPUT delimiter bars
 765      WIDTH width of column, if 0, use variable width
 766
 767      This routine was deprecated in libpq-6.5.
 768
 769  - Unimplemented Function: int PQmblen (char *s, int encoding)
 770      Determine length of a multibyte encoded char at `*s'.  S encoded
 771      string ENCODING type of encoding
 772
 773      Compatibility note:  This function was introduced in libpq-7.0.
 774
 775  - Unimplemented Function: void PQtrace (PGconn *conn, FILE *debug_port)
 776      Enable tracing on `debug_port'.  CONN database connection object.
 777      DEBUG_PORT C output stream to use.
 778
 779  - Unimplemented Function: void PQuntrace (PGconn *conn)
 780      Disable tracing.  CONN database connection object.
 781
 782  - Unimplemented Function: char *PQoidStatus (PGconn *conn)
 783      Return the object id as a string of the last tuple inserted.  CONN
 784      database connection object.
 785
 786      Compatibility note: This function is deprecated in libpq-7.0,
 787      however it is used internally by the XEmacs binding code when
 788      linked against versions prior to 7.0.
 789
 790  - Unimplemented Function: PGresult *PQfn (PGconn *conn, int fnid, int
 791           *result_buf, int *result_len, int result_is_int, PQArgBlock
 792           *args, int nargs)
 793      "Fast path" interface -- not really recommended for application use
 794      CONN A database connection object.  FNID RESULT_BUF RESULT_LEN
 795      RESULT_IS_INT ARGS NARGS
 796
 797    The following set of very low level large object functions aren't
 798 appropriate to be exported to Lisp.
 799
 800  - Unimplemented Function: int pq-lo-open (PGconn *conn, int lobjid,
 801           int mode)
 802      CONN a database connection object.  LOBJID a large object ID.
 803      MODE opening modes.
 804
 805  - Unimplemented Function: int pq-lo-close (PGconn *conn, int fd)
 806      CONN a database connection object.  FD a large object file
 807      descriptor
 808
 809  - Unimplemented Function: int pq-lo-read (PGconn *conn, int fd, char
 810           *buf, int len)
 811      CONN a database connection object.  FD a large object file
 812      descriptor.  BUF buffer to read into.  LEN size of buffer.
 813
 814  - Unimplemented Function: int pq-lo-write (PGconn *conn, int fd, char
 815           *buf, size_t len)
 816      CONN a database connection object.  FD a large object file
 817      descriptor.  BUF buffer to write from.  LEN size of buffer.
 818
 819  - Unimplemented Function: int pq-lo-lseek (PGconn *conn, int fd, int
 820           offset, int whence)
 821      CONN a database connection object.  FD a large object file
 822      descriptor.  OFFSET WHENCE
 823
 824  - Unimplemented Function: int pq-lo-creat (PGconn *conn, int mode)
 825      CONN a database connection object.  MODE opening modes.
 826
 827  - Unimplemented Function: int pq-lo-tell (PGconn *conn, int fd)
 828      CONN a database connection object.  FD a large object file
 829      descriptor.
 830
 831  - Unimplemented Function: int pq-lo-unlink (PGconn *conn, int lobjid)
 832      CONN a database connection object.  LBOJID a large object ID.
 833
 834 \1f
 835 File: lispref.info,  Node: XEmacs PostgreSQL libpq Examples,  Prev: XEmacs PostgreSQL libpq API,  Up: PostgreSQL Support
 836
 837 XEmacs PostgreSQL libpq Examples
 838 ================================
 839
 840    This is an example of one method of establishing an asynchronous
 841 connection.
 842
 843      (defun database-poller (P)
 844        (message "%S before poll" (pq-pgconn P 'pq::status))
 845        (pq-connect-poll P)
 846        (message "%S after poll" (pq-pgconn P 'pq::status))
 847        (if (eq (pq-pgconn P 'pq::status) 'pg::connection-ok)
 848            (message "Done!")
 849          (add-timeout .1 'database-poller P)))
 850           => database-poller
 851      (progn
 852        (setq P (pq-connect-start ""))
 853        (add-timeout .1 'database-poller P))
 854           => pg::connection-started before poll
 855           => pg::connection-made after poll
 856           => pg::connection-made before poll
 857           => pg::connection-awaiting-response after poll
 858           => pg::connection-awaiting-response before poll
 859           => pg::connection-auth-ok after poll
 860           => pg::connection-auth-ok before poll
 861           => pg::connection-setenv after poll
 862           => pg::connection-setenv before poll
 863           => pg::connection-ok after poll
 864           => Done!
 865      P
 866           => #<PGconn localhost:25432 steve/steve>
 867
 868    Here is an example of one method of doing an asynchronous reset.
 869
 870      (defun database-poller (P)
 871        (let (PS)
 872          (message "%S before poll" (pq-pgconn P 'pq::status))
 873          (setq PS (pq-reset-poll P))
 874          (message "%S after poll [%S]" (pq-pgconn P 'pq::status) PS)
 875          (if (eq (pq-pgconn P 'pq::status) 'pg::connection-ok)
 876         (message "Done!")
 877            (add-timeout .1 'database-poller P))))
 878           => database-poller
 879      (progn
 880        (pq-reset-start P)
 881        (add-timeout .1 'database-poller P))
 882           => pg::connection-started before poll
 883           => pg::connection-made after poll [pgres::polling-writing]
 884           => pg::connection-made before poll
 885           => pg::connection-awaiting-response after poll [pgres::polling-reading]
 886           => pg::connection-awaiting-response before poll
 887           => pg::connection-setenv after poll [pgres::polling-reading]
 888           => pg::connection-setenv before poll
 889           => pg::connection-ok after poll [pgres::polling-ok]
 890           => Done!
 891      P
 892           => #<PGconn localhost:25432 steve/steve>
 893
 894    And finally, an asynchronous query.
 895
 896      (defun database-poller (P)
 897        (let (R)
 898          (pq-consume-input P)
 899          (if (pq-is-busy P)
 900         (add-timeout .1 'database-poller P)
 901            (setq R (pq-get-result P))
 902            (if R
 903           (progn
 904             (push R result-list)
 905             (add-timeout .1 'database-poller P))))))
 906           => database-poller
 907      (when (pq-send-query P "SELECT * FROM xemacs_test;")
 908        (setq result-list nil)
 909        (add-timeout .1 'database-poller P))
 910           => 885
 911      ;; wait a moment
 912      result-list
 913           => (#<PGresult PGRES_TUPLES_OK - SELECT>)
 914
 915    Here is an example showing how multiple SQL statements in a single
 916 query can have all their results collected.
 917      ;; Using the same `database-poller' function from the previous example
 918      (when (pq-send-query P "SELECT * FROM xemacs_test;
 919      SELECT * FROM pg_database;
 920      SELECT * FROM pg_user;")
 921        (setq result-list nil)
 922        (add-timeout .1 'database-poller P))
 923           => 1782
 924      ;; wait a moment
 925      result-list
 926           => (#<PGresult PGRES_TUPLES_OK - SELECT> #<PGresult PGRES_TUPLES_OK - SELECT> #<PGresult PGRES_TUPLES_OK - SELECT>)
 927
 928    Here is an example which illustrates collecting all data from a
 929 query, including the field names.
 930
 931      (defun pg-util-query-results (results)
 932        "Retrieve results of last SQL query into a list structure."
 933        (let ((i (1- (pq-ntuples R)))
 934         j l1 l2)
 935          (while (>= i 0)
 936            (setq j (1- (pq-nfields R)))
 937            (setq l2 nil)
 938            (while (>= j 0)
 939         (push (pq-get-value R i j) l2)
 940         (decf j))
 941            (push l2 l1)
 942            (decf i))
 943          (setq j (1- (pq-nfields R)))
 944          (setq l2 nil)
 945          (while (>= j 0)
 946            (push (pq-fname R j) l2)
 947            (decf j))
 948          (push l2 l1)
 949          l1))
 950           => pg-util-query-results
 951      (setq R (pq-exec P "SELECT * FROM xemacs_test ORDER BY field2 DESC;"))
 952           => #<PGresult PGRES_TUPLES_OK - SELECT>
 953      (pg-util-query-results R)
 954           => (("f1" "field2") ("a" "97") ("b" "97") ("stuff" "42") ("a string" "12") ("foo" "10") ("string" "2") ("text" "1"))
 955
 956    Here is an example of a query that uses a database cursor.
 957
 958      (let (data R)
 959        (setq R (pq-exec P "BEGIN;"))
 960        (setq R (pq-exec P "DECLARE k_cursor CURSOR FOR SELECT * FROM xemacs_test ORDER BY f1 DESC;"))
 961
 962        (setq R (pq-exec P "FETCH k_cursor;"))
 963        (while (eq (pq-ntuples R) 1)
 964          (push (list (pq-get-value R 0 0) (pq-get-value R 0 1)) data)
 965          (setq R (pq-exec P "FETCH k_cursor;")))
 966        (setq R (pq-exec P "END;"))
 967        data)
 968           => (("a" "97") ("a string" "12") ("b" "97") ("foo" "10") ("string" "2") ("stuff" "42") ("text" "1"))
 969
 970    Here's another example of cursors, this time with a Lisp macro to
 971 implement a mapping function over a table.
 972
 973      (defmacro map-db (P table condition callout)
 974        `(let (R)
 975           (pq-exec ,P "BEGIN;")
 976           (pq-exec ,P (concat "DECLARE k_cursor CURSOR FOR SELECT * FROM "
 977                          ,table
 978                          " "
 979                          ,condition
 980                          " ORDER BY f1 DESC;"))
 981           (setq R (pq-exec P "FETCH k_cursor;"))
 982           (while (eq (pq-ntuples R) 1)
 983             (,callout (pq-get-value R 0 0) (pq-get-value R 0 1))
 984             (setq R (pq-exec P "FETCH k_cursor;")))
 985           (pq-exec P "END;")))
 986           => map-db
 987      (defun callback (arg1 arg2)
 988        (message "arg1 = %s, arg2 = %s" arg1 arg2))
 989           => callback
 990      (map-db P "xemacs_test" "WHERE field2 > 10" callback)
 991           => arg1 = stuff, arg2 = 42
 992           => arg1 = b, arg2 = 97
 993           => arg1 = a string, arg2 = 12
 994           => arg1 = a, arg2 = 97
 995           => #<PGresult PGRES_COMMAND_OK - COMMIT>
 996
 997 \1f
 998 File: lispref.info,  Node: Internationalization,  Next: MULE,  Prev: PostgreSQL Support,  Up: Top
 999
1000 Internationalization
1001 ********************
1002
1003 * Menu:
1004
1005 * I18N Levels 1 and 2:: Support for different time, date, and currency formats.
1006 * I18N Level 3::        Support for localized messages.
1007 * I18N Level 4::        Support for Asian languages.
1008
1009 \1f
1010 File: lispref.info,  Node: I18N Levels 1 and 2,  Next: I18N Level 3,  Up: Internationalization
1011
1012 I18N Levels 1 and 2
1013 ===================
1014
1015    XEmacs is now compliant with I18N levels 1 and 2.  Specifically,
1016 this means that it is 8-bit clean and correctly handles time and date
1017 functions.  XEmacs will correctly display the entire ISO-Latin 1
1018 character set.
1019
1020    The compose key may now be used to create any character in the
1021 ISO-Latin 1 character set not directly available via the keyboard..  In
1022 order for the compose key to work it is necessary to load the file
1023 `x-compose.el'.  At any time while composing a character, `C-h' will
1024 display all valid completions and the character which would be produced.
1025
1026 \1f
1027 File: lispref.info,  Node: I18N Level 3,  Next: I18N Level 4,  Prev: I18N Levels 1 and 2,  Up: Internationalization
1028
1029 I18N Level 3
1030 ============
1031
1032 * Menu:
1033
1034 * Level 3 Basics::
1035 * Level 3 Primitives::
1036 * Dynamic Messaging::
1037 * Domain Specification::
1038 * Documentation String Extraction::
1039
1040 \1f
1041 File: lispref.info,  Node: Level 3 Basics,  Next: Level 3 Primitives,  Up: I18N Level 3
1042
1043 Level 3 Basics
1044 --------------
1045
1046    XEmacs now provides alpha-level functionality for I18N Level 3.
1047 This means that everything necessary for full messaging is available,
1048 but not every file has been converted.
1049
1050    The two message files which have been created are `src/emacs.po' and
1051 `lisp/packages/mh-e.po'.  Both files need to be converted using
1052 `msgfmt', and the resulting `.mo' files placed in some locale's
1053 `LC_MESSAGES' directory.  The test "translations" in these files are
1054 the original messages prefixed by `TRNSLT_'.
1055
1056    The domain for a variable is stored on the variable's property list
1057 under the property name VARIABLE-DOMAIN.  The function
1058 `documentation-property' uses this information when translating a
1059 variable's documentation.
1060
1061 \1f
1062 File: lispref.info,  Node: Level 3 Primitives,  Next: Dynamic Messaging,  Prev: Level 3 Basics,  Up: I18N Level 3
1063
1064 Level 3 Primitives
1065 ------------------
1066
1067  - Function: gettext string
1068      This function looks up STRING in the default message domain and
1069      returns its translation.  If `I18N3' was not enabled when XEmacs
1070      was compiled, it just returns STRING.
1071
1072  - Function: dgettext domain string
1073      This function looks up STRING in the specified message domain and
1074      returns its translation.  If `I18N3' was not enabled when XEmacs
1075      was compiled, it just returns STRING.
1076
1077  - Function: bind-text-domain domain pathname
1078      This function associates a pathname with a message domain.  Here's
1079      how the path to message file is constructed under SunOS 5.x:
1080
1081           `{pathname}/{LANG}/LC_MESSAGES/{domain}.mo'
1082
1083      If `I18N3' was not enabled when XEmacs was compiled, this function
1084      does nothing.
1085
1086  - Special Form: domain string
1087      This function specifies the text domain used for translating
1088      documentation strings and interactive prompts of a function.  For
1089      example, write:
1090
1091           (defun foo (arg) "Doc string" (domain "emacs-foo") ...)
1092
1093      to specify `emacs-foo' as the text domain of the function `foo'.
1094      The "call" to `domain' is actually a declaration rather than a
1095      function; when actually called, `domain' just returns `nil'.
1096
1097  - Function: domain-of function
1098      This function returns the text domain of FUNCTION; it returns
1099      `nil' if it is the default domain.  If `I18N3' was not enabled
1100      when XEmacs was compiled, it always returns `nil'.
1101
1102 \1f
1103 File: lispref.info,  Node: Dynamic Messaging,  Next: Domain Specification,  Prev: Level 3 Primitives,  Up: I18N Level 3
1104
1105 Dynamic Messaging
1106 -----------------
1107
1108    The `format' function has been extended to permit you to change the
1109 order of parameter insertion.  For example, the conversion format
1110 `%1$s' inserts parameter one as a string, while `%2$s' inserts
1111 parameter two.  This is useful when creating translations which require
1112 you to change the word order.
1113
1114 \1f
1115 File: lispref.info,  Node: Domain Specification,  Next: Documentation String Extraction,  Prev: Dynamic Messaging,  Up: I18N Level 3
1116
1117 Domain Specification
1118 --------------------
1119
1120    The default message domain of XEmacs is `emacs'.  For add-on
1121 packages, it is best to use a different domain.  For example, let us
1122 say we want to convert the "gorilla" package to use the domain
1123 `emacs-gorilla'.  To translate the message "What gorilla?", use
1124 `dgettext' as follows:
1125
1126      (dgettext "emacs-gorilla" "What gorilla?")
1127
1128    A function (or macro) which has a documentation string or an
1129 interactive prompt needs to be associated with the domain in order for
1130 the documentation or prompt to be translated.  This is done with the
1131 `domain' special form as follows:
1132
1133      (defun scratch (location)
1134        "Scratch the specified location."
1135        (domain "emacs-gorilla")
1136        (interactive "sScratch: ")
1137        ... )
1138
1139    It is most efficient to specify the domain in the first line of the
1140 function body, before the `interactive' form.
1141
1142    For variables and constants which have documentation strings,
1143 specify the domain after the documentation.
1144
1145  - Special Form: defvar symbol [value [doc-string [domain]]]
1146      Example:
1147           (defvar weight 250 "Weight of gorilla, in pounds." "emacs-gorilla")
1148
1149  - Special Form: defconst symbol [value [doc-string [domain]]]
1150      Example:
1151           (defconst limbs 4 "Number of limbs" "emacs-gorilla")
1152
1153  - Function: autoload function filename &optional docstring interactive
1154           type
1155      This function defines FUNCTION to autoload from FILENAME Example:
1156           (autoload 'explore "jungle" "Explore the jungle." nil nil "emacs-gorilla")
1157
1158 \1f
1159 File: lispref.info,  Node: Documentation String Extraction,  Prev: Domain Specification,  Up: I18N Level 3
1160
1161 Documentation String Extraction
1162 -------------------------------
1163
1164    The utility `etc/make-po' scans the file `DOC' to extract
1165 documentation strings and creates a message file `doc.po'.  This file
1166 may then be inserted within `emacs.po'.
1167
1168    Currently, `make-po' is hard-coded to read from `DOC' and write to
1169 `doc.po'.  In order to extract documentation strings from an add-on
1170 package, first run `make-docfile' on the package to produce the `DOC'
1171 file.  Then run `make-po -p' with the `-p' argument to indicate that we
1172 are extracting documentation for an add-on package.
1173
1174    (The `-p' argument is a kludge to make up for a subtle difference
1175 between pre-loaded documentation and add-on documentation:  For add-on
1176 packages, the final carriage returns in the strings produced by
1177 `make-docfile' must be ignored.)
1178
1179 \1f
1180 File: lispref.info,  Node: I18N Level 4,  Prev: I18N Level 3,  Up: Internationalization
1181
1182 I18N Level 4
1183 ============
1184
1185    The Asian-language support in XEmacs is called "MULE".  *Note MULE::.
1186
1187 \1f
1188 File: lispref.info,  Node: MULE,  Next: Tips,  Prev: Internationalization,  Up: Top
1189
1190 MULE
1191 ****
1192
1193    "MULE" is the name originally given to the version of GNU Emacs
1194 extended for multi-lingual (and in particular Asian-language) support.
1195 "MULE" is short for "MUlti-Lingual Emacs".  It is an extension and
1196 complete rewrite of Nemacs ("Nihon Emacs" where "Nihon" is the Japanese
1197 word for "Japan"), which only provided support for Japanese.  XEmacs
1198 refers to its multi-lingual support as "MULE support" since it is based
1199 on "MULE".
1200
1201 * Menu:
1202
1203 * Internationalization Terminology::
1204                         Definition of various internationalization terms.
1205 * Charsets::            Sets of related characters.
1206 * MULE Characters::     Working with characters in XEmacs/MULE.
1207 * Composite Characters:: Making new characters by overstriking other ones.
1208 * Coding Systems::      Ways of representing a string of chars using integers.
1209 * CCL::                 A special language for writing fast converters.
1210 * Category Tables::     Subdividing charsets into groups.
1211