1 This is ../info/lispref.info, produced by makeinfo version 4.0b from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: libpq Lisp Symbols and DataTypes, Next: Synchronous Interface Functions, Prev: libpq Lisp Variables, Up: XEmacs PostgreSQL libpq API
55 libpq Lisp Symbols and Datatypes
56 --------------------------------
58 The following set of symbols are used to represent the intermediate
59 states involved in the asynchronous interface.
61 - Symbol: pgres::polling-failed
62 Undocumented. A fatal error has occurred during processing of an
63 asynchronous operation.
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.
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.
73 - Symbol: pgres::polling-ok
74 An asynchronous operation has successfully completed.
76 - Symbol: pgres::polling-active
77 An intermediate status return during an asynchronous operation.
78 One can call the poll function again immediately.
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
91 Database user's password
94 Hostname database server is running on
97 TCP port number used in the connection
102 Compatibility note: Debugging TTYs are not used in the
106 Additional server options
109 Connection status. Possible return values are shown in the
112 The normal, connected status.
115 The connection is not open and the PGconn object needs
116 to be deleted by `pq-finish'.
118 `pg::connection-started'
119 An asynchronous connection has been started, but is not
122 `pg::connection-made'
123 An asynchronous connect has been made, and there is data
126 `pg::connection-awaiting-response'
127 Awaiting data from the backend during an asynchronous
130 `pg::connection-auth-ok'
131 Received authentication, waiting for the backend to
134 `pg::connection-setenv'
135 Negotiating environment during an asynchronous
139 The last error message that was delivered to this connection.
142 The process ID of the backend database server.
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:
148 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
149 => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
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:
155 (pq-exec P "CREATE TABLE a_new_table (i int);")
156 => #<PGresult PGRES_COMMAND_OK - CREATE>
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
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>
169 Lastly, when the underlying PGresult object has been deallocated
170 directly by `pq-clear' the printed representation will look like:
173 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
178 The following set of functions are accessors to various data in the
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.
185 A query contained no text. This is usually the result of a
186 recoverable error, or a minor programming error.
189 A query command that doesn't return anything was executed
190 properly by the backend.
193 A query command that returns tuples was executed properly by
197 Copy Out data transfer is in progress.
200 Copy In data transfer is in progress.
202 `pgres::bad-response'
203 An unexpected response was received from the backend.
205 `pgres::nonfatal-error'
206 Undocumented. This value is returned when the libpq function
207 `PQresultStatus' is called with a NULL pointer.
210 Undocumented. An error has occurred in processing the query
211 and the operation was not completed.
213 - Function: pq-res-status result
214 Return the query result status as a string, not a symbol. RESULT
215 is a PGresult object.
217 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
218 => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
222 - Function: pq-result-error-message result
223 Return an error message generated by the query, if any. RESULT is
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 \"-\"
232 - Function: pq-ntuples result
233 Return the number of tuples in the query result. RESULT is a
236 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
237 => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
241 - Function: pq-nfields result
242 Return the number of fields in each tuple of the query result.
243 RESULT is a PGresult object.
245 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
246 => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
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.
254 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
255 => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
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.
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))
270 => ("id" "shikona" "rank")
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>
280 (pq-fnumber R "Not a field")
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
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.
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.
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.
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))
307 => ((23 23) (25 25) (25 25))
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
314 Both tuples and fields are numbered from zero.
316 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
317 => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
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.
330 (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
331 => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
332 (pq-get-length R 0 1)
334 (pq-get-length R 1 1)
336 (pq-get-length R 2 1)
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.
344 - Function: pq-cmd-status result
345 Return a summary string from the query. RESULT is a PGresult
347 (pq-exec P "INSERT INTO xemacs_test
348 VALUES (6, 'Wakanohana', 'Yokozuna');")
349 => #<PGresult PGRES_COMMAND_OK[1] - 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>
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.
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.
368 (setq R (pq-exec P "INSERT INTO xemacs_test VALUES
369 (7, 'Takanohana', 'Yokuzuna');"))
370 => #<PGresult PGRES_COMMAND_OK[1] - INSERT 38688 1>
373 (setq R (pq-exec P "SELECT * from xemacs_test;"))
374 => #<PGresult PGRES_TUPLES_OK[7] - SELECT>
377 (setq R (pq-exec P "DELETE FROM xemacs_test
378 WHERE shikona LIKE '%hana';"))
379 => #<PGresult PGRES_COMMAND_OK[2] - DELETE 2>
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.
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>
397 (setq R (pq-exec P "SELECT shikona FROM xemacs_test
398 WHERE rank='Maegashira';"))
399 => #<PGresult PGRES_TUPLES_OK[2] - SELECT>
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
408 The caller is responsible for making sure the return value gets
412 File: lispref.info, Node: Synchronous Interface Functions, Next: Asynchronous Interface Functions, Prev: libpq Lisp Symbols and DataTypes, Up: XEmacs PostgreSQL libpq API
414 Synchronous Interface Functions
415 -------------------------------
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.
431 Database connection objects which have been disconnected and will
432 generate an immediate error if they are used look like:
434 Bad connections can be reestablished with `pq-reset', or deleted
435 entirely with `pq-finish'.
437 A database connection object that has been deleted looks like:
438 (let ((P1 (pq-connectdb "")))
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:
450 (let ((P (pq-connectiondb "")))
453 (...)) ; access database here
456 The following options are available in the options string:
458 Authentication type. Same as PGAUTHTYPE. This is no longer
462 Database user name. Same as PGUSER.
468 Database name. Same as PGDATABASE
471 Symbolic hostname. Same as PGHOST.
474 Host address as four octets (eg. like 192.168.1.1).
477 TCP port to connect to. Same as PGPORT.
480 Debugging TTY. Same as PGTTY. This value is suppressed in
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.
488 - Function: pq-reset conn
489 Reestablish database connection. CONN A database connection
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.
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.
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>
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.
516 - Function: PQsetenv conn
517 Synchronous transfer of environment variables to a backend CONN A
518 database connection object.
520 Environment variable transfer is done as a normal part of database
523 Compatibility note: This function was present but not documented
524 in versions of libpq prior to 7.0.
527 File: lispref.info, Node: Asynchronous Interface Functions, Next: Large Object Support, Prev: Synchronous Interface Functions, Up: XEmacs PostgreSQL libpq API
529 Asynchronous Interface Functions
530 --------------------------------
532 Making command by command examples is too complex with the
533 asynchronous interface functions. See the examples section for
534 complete calling sequences.
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.
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.
546 - Function: pq-is-busy conn
547 Returns t if `pq-get-result' would block waiting for input. CONN
548 A database connection object.
550 - Function: pq-consume-input conn
551 Consume any available input from the backend. CONN A database
554 Nil is returned if anything bad happens.
556 - Function: pq-reset-start conn
557 Reset connection to the backend asynchronously. CONN A database
560 - Function: pq-reset-poll conn
561 Poll an asynchronous reset for completion CONN A database
564 - Function: pq-reset-cancel conn
565 Attempt to request cancellation of the current operation. CONN A
566 database connection object.
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
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)
579 - Function: pq-get-result conn
580 Retrieve an asynchronous result from a query. CONN A database
583 `nil' is returned when no more query work remains.
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.
591 - Function: pq-is-nonblocking conn
592 Return the blocking status of the database connection CONN A
593 database connection object.
595 - Function: pq-flush conn
596 Force the write buffer to be written (or at least try) CONN A
597 database connection object.
599 - Function: PQsetenvStart conn
600 Start asynchronously passing environment variables to a backend.
601 CONN A database connection object.
603 Compatibility note: this function is only available with libpq-7.0.
605 - Function: PQsetenvPoll conn
606 Check an asynchronous environment variables transfer for
607 completion. CONN A database connection object.
609 Compatibility note: this function is only available with libpq-7.0.
611 - Function: PQsetenvAbort conn
612 Attempt to terminate an asynchronous environment variables
613 transfer. CONN A database connection object.
615 Compatibility note: this function is only available with libpq-7.0.
618 File: lispref.info, Node: Large Object Support, Next: Other libpq Functions, Prev: Asynchronous Interface Functions, Up: XEmacs PostgreSQL libpq API
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
627 On success, the object id is returned.
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.
635 File: lispref.info, Node: Other libpq Functions, Next: Unimplemented libpq Functions, Prev: Large Object Support, Up: XEmacs PostgreSQL libpq API
637 Other libpq Functions
638 ---------------------
640 - Function: pq-finish conn
641 Destroy a database connection object by calling free on it. CONN
642 a database connection object
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
651 After calling this routine, the printed representation of the
652 XEmacs wrapper object will contain the string "DEAD".
654 - Function: pq-client-encoding conn
655 Return the client encoding as an integer code. CONN a database
658 (pq-client-encoding P)
661 Compatibility note: This function did not exist prior to libpq-7.0
662 and does not exist in a non-Mule XEmacs.
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
668 (pq-set-client-encoding P "EUC_JP")
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")
679 Compatibility note: This function did not exist prior to libpq-7.0
680 and does not exist in a non-Mule XEmacs.
682 - Function: pq-env-2-encoding
683 Return the integer code representing the coding system in
688 Compatibility note: This function did not exist prior to libpq-7.0
689 and does not exist in a non-Mule XEmacs.
691 - Function: pq-clear res
692 Destroy a query result object by calling free() on it. RES a
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.
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.
711 File: lispref.info, Node: Unimplemented libpq Functions, Prev: Other libpq Functions, Up: XEmacs PostgreSQL libpq API
713 Unimplemented libpq Functions
714 -----------------------------
716 - Unimplemented Function: PGconn *PQsetdbLogin (char *pghost, char
717 *pgport, char *pgoptions, char *pgtty, char *dbName, char
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.
726 This routine is deprecated as of libpq-7.0, and its functionality
727 can be replaced by external Lisp code if needed.
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
737 This routine was deprecated in libpq-6.5.
739 - Unimplemented Function: int PQsocket (PGconn *conn)
740 Return socket file descriptor to a backend database process. CONN
741 database connection object.
743 - Unimplemented Function: void PQprint (FILE *fout, PGresult *res,
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.
749 This routine is deprecated as of libpq-7.0 and cannot be sensibly
750 exported to XEmacs Lisp.
752 - Unimplemented Function: void PQdisplayTuples (PGresult *res, FILE
753 *fp, int fillAlign, char *fieldSep, int printHeader, int
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
759 This routine was deprecated in libpq-6.5.
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
767 This routine was deprecated in libpq-6.5.
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
773 Compatibility note: This function was introduced in libpq-7.0.
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.
779 - Unimplemented Function: void PQuntrace (PGconn *conn)
780 Disable tracing. CONN database connection object.
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.
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.
790 - Unimplemented Function: PGresult *PQfn (PGconn *conn, int fnid, int
791 *result_buf, int *result_len, int result_is_int, PQArgBlock
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
797 The following set of very low level large object functions aren't
798 appropriate to be exported to Lisp.
800 - Unimplemented Function: int pq-lo-open (PGconn *conn, int lobjid,
802 CONN a database connection object. LOBJID a large object ID.
805 - Unimplemented Function: int pq-lo-close (PGconn *conn, int fd)
806 CONN a database connection object. FD a large object file
809 - Unimplemented Function: int pq-lo-read (PGconn *conn, int fd, char
811 CONN a database connection object. FD a large object file
812 descriptor. BUF buffer to read into. LEN size of buffer.
814 - Unimplemented Function: int pq-lo-write (PGconn *conn, int fd, char
816 CONN a database connection object. FD a large object file
817 descriptor. BUF buffer to write from. LEN size of buffer.
819 - Unimplemented Function: int pq-lo-lseek (PGconn *conn, int fd, int
821 CONN a database connection object. FD a large object file
822 descriptor. OFFSET WHENCE
824 - Unimplemented Function: int pq-lo-creat (PGconn *conn, int mode)
825 CONN a database connection object. MODE opening modes.
827 - Unimplemented Function: int pq-lo-tell (PGconn *conn, int fd)
828 CONN a database connection object. FD a large object file
831 - Unimplemented Function: int pq-lo-unlink (PGconn *conn, int lobjid)
832 CONN a database connection object. LBOJID a large object ID.
835 File: lispref.info, Node: XEmacs PostgreSQL libpq Examples, Prev: XEmacs PostgreSQL libpq API, Up: PostgreSQL Support
837 XEmacs PostgreSQL libpq Examples
838 ================================
840 This is an example of one method of establishing an asynchronous
843 (defun database-poller (P)
844 (message "%S before poll" (pq-pgconn P 'pq::status))
846 (message "%S after poll" (pq-pgconn P 'pq::status))
847 (if (eq (pq-pgconn P 'pq::status) 'pg::connection-ok)
849 (add-timeout .1 'database-poller P)))
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
866 => #<PGconn localhost:25432 steve/steve>
868 Here is an example of one method of doing an asynchronous reset.
870 (defun database-poller (P)
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)
877 (add-timeout .1 'database-poller 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]
892 => #<PGconn localhost:25432 steve/steve>
894 And finally, an asynchronous query.
896 (defun database-poller (P)
900 (add-timeout .1 'database-poller P)
901 (setq R (pq-get-result P))
905 (add-timeout .1 'database-poller P))))))
907 (when (pq-send-query P "SELECT * FROM xemacs_test;")
908 (setq result-list nil)
909 (add-timeout .1 'database-poller P))
913 => (#<PGresult PGRES_TUPLES_OK - SELECT>)
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))
926 => (#<PGresult PGRES_TUPLES_OK - SELECT> #<PGresult PGRES_TUPLES_OK - SELECT> #<PGresult PGRES_TUPLES_OK - SELECT>)
928 Here is an example which illustrates collecting all data from a
929 query, including the field names.
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)))
936 (setq j (1- (pq-nfields R)))
939 (push (pq-get-value R i j) l2)
943 (setq j (1- (pq-nfields R)))
946 (push (pq-fname R j) l2)
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"))
956 Here is an example of a query that uses a database cursor.
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;"))
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;"))
968 => (("a" "97") ("a string" "12") ("b" "97") ("foo" "10") ("string" "2") ("stuff" "42") ("text" "1"))
970 Here's another example of cursors, this time with a Lisp macro to
971 implement a mapping function over a table.
973 (defmacro map-db (P table condition callout)
975 (pq-exec ,P "BEGIN;")
976 (pq-exec ,P (concat "DECLARE k_cursor CURSOR FOR SELECT * FROM "
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;")))
987 (defun callback (arg1 arg2)
988 (message "arg1 = %s, arg2 = %s" arg1 arg2))
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>
998 File: lispref.info, Node: Internationalization, Next: MULE, Prev: PostgreSQL Support, Up: Top
1000 Internationalization
1001 ********************
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.
1010 File: lispref.info, Node: I18N Levels 1 and 2, Next: I18N Level 3, Up: Internationalization
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
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.
1027 File: lispref.info, Node: I18N Level 3, Next: I18N Level 4, Prev: I18N Levels 1 and 2, Up: Internationalization
1035 * Level 3 Primitives::
1036 * Dynamic Messaging::
1037 * Domain Specification::
1038 * Documentation String Extraction::
1041 File: lispref.info, Node: Level 3 Basics, Next: Level 3 Primitives, Up: I18N Level 3
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.
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_'.
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.
1062 File: lispref.info, Node: Level 3 Primitives, Next: Dynamic Messaging, Prev: Level 3 Basics, Up: I18N Level 3
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.
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.
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:
1081 `{pathname}/{LANG}/LC_MESSAGES/{domain}.mo'
1083 If `I18N3' was not enabled when XEmacs was compiled, this function
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
1091 (defun foo (arg) "Doc string" (domain "emacs-foo") ...)
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'.
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'.
1103 File: lispref.info, Node: Dynamic Messaging, Next: Domain Specification, Prev: Level 3 Primitives, Up: I18N Level 3
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.
1115 File: lispref.info, Node: Domain Specification, Next: Documentation String Extraction, Prev: Dynamic Messaging, Up: I18N Level 3
1117 Domain Specification
1118 --------------------
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:
1126 (dgettext "emacs-gorilla" "What gorilla?")
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:
1133 (defun scratch (location)
1134 "Scratch the specified location."
1135 (domain "emacs-gorilla")
1136 (interactive "sScratch: ")
1139 It is most efficient to specify the domain in the first line of the
1140 function body, before the `interactive' form.
1142 For variables and constants which have documentation strings,
1143 specify the domain after the documentation.
1145 - Special Form: defvar symbol [value [doc-string [domain]]]
1147 (defvar weight 250 "Weight of gorilla, in pounds." "emacs-gorilla")
1149 - Special Form: defconst symbol [value [doc-string [domain]]]
1151 (defconst limbs 4 "Number of limbs" "emacs-gorilla")
1153 - Function: autoload function filename &optional docstring interactive
1155 This function defines FUNCTION to autoload from FILENAME Example:
1156 (autoload 'explore "jungle" "Explore the jungle." nil nil "emacs-gorilla")
1159 File: lispref.info, Node: Documentation String Extraction, Prev: Domain Specification, Up: I18N Level 3
1161 Documentation String Extraction
1162 -------------------------------
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'.
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.
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.)
1180 File: lispref.info, Node: I18N Level 4, Prev: I18N Level 3, Up: Internationalization
1185 The Asian-language support in XEmacs is called "MULE". *Note MULE::.
1188 File: lispref.info, Node: MULE, Next: Tips, Prev: Internationalization, Up: Top
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
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.