X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-43;h=18337d74dedd8ccc6def722f538daa251a29e65a;hb=52838d5d5614c339626bec4abba4699995150678;hp=cb0a7a1d6db95aa8c5274d4121fd4bdaca38df83;hpb=82da33b61c3e2dd2937db17b75b2838188793053;p=chise%2Fxemacs-chise.git- diff --git a/info/lispref.info-43 b/info/lispref.info-43 index cb0a7a1..18337d7 100644 --- a/info/lispref.info-43 +++ b/info/lispref.info-43 @@ -1,5 +1,5 @@ -This is Info file ../info/lispref.info, produced by Makeinfo version -1.68 from the input file lispref/lispref.texi. +This is ../info/lispref.info, produced by makeinfo version 4.0 from +lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor START-INFO-DIR-ENTRY @@ -50,1401 +50,1162 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -File: lispref.info, Node: Building XEmacs, Next: Pure Storage, Up: Building XEmacs and Object Allocation - -Building XEmacs -=============== - - This section explains the steps involved in building the XEmacs -executable. You don't have to know this material to build and install -XEmacs, since the makefiles do all these things automatically. This -information is pertinent to XEmacs maintenance. - - The `XEmacs Internals Manual' contains more information about this. - - Compilation of the C source files in the `src' directory produces an -executable file called `temacs', also called a "bare impure XEmacs". -It contains the XEmacs Lisp interpreter and I/O routines, but not the -editing commands. - - Before XEmacs is actually usable, a number of Lisp files need to be -loaded. These define all the editing commands, plus most of the startup -code and many very basic Lisp primitives. This is accomplished by -loading the file `loadup.el', which in turn loads all of the other -standardly-loaded Lisp files. - - It takes a substantial time to load the standard Lisp files. -Luckily, you don't have to do this each time you run XEmacs; `temacs' -can dump out an executable program called `xemacs' that has these files -preloaded. `xemacs' starts more quickly because it does not need to -load the files. This is the XEmacs executable that is normally -installed. - - To create `xemacs', use the command `temacs -batch -l loadup dump'. -The purpose of `-batch' here is to tell `temacs' to run in -non-interactive, command-line mode. (`temacs' can *only* run in this -fashion. Part of the code required to initialize frames and faces is -in Lisp, and must be loaded before XEmacs is able to create any frames.) -The argument `dump' tells `loadup.el' to dump a new executable named -`xemacs'. - - The dumping process is highly system-specific, and some operating -systems don't support dumping. On those systems, you must start XEmacs -with the `temacs -batch -l loadup run-temacs' command each time you use -it. This takes a substantial time, but since you need to start Emacs -once a day at most--or once a week if you never log out--the extra time -is not too severe a problem. (In older versions of Emacs, you started -Emacs from `temacs' using `temacs -l loadup'.) - - You are free to start XEmacs directly from `temacs' if you want, -even if there is already a dumped `xemacs'. Normally you wouldn't want -to do that; but the Makefiles do this when you rebuild XEmacs using -`make all-elc', which builds XEmacs and simultaneously compiles any -out-of-date Lisp files. (You need `xemacs' in order to compile Lisp -files. However, you also need the compiled Lisp files in order to dump -out `xemacs'. If both of these are missing or corrupted, you are out -of luck unless you're able to bootstrap `xemacs' from `temacs'. Note -that `make all-elc' actually loads the alternative loadup file -`loadup-el.el', which works like `loadup.el' but disables the -pure-copying process and forces XEmacs to ignore any compiled Lisp -files even if they exist.) - - You can specify additional files to preload by writing a library -named `site-load.el' that loads them. You may need to increase the -value of `PURESIZE', in `src/puresize.h', to make room for the -additional files. You should *not* modify this file directly, however; -instead, use the `--puresize' configuration option. (If you run out of -pure space while dumping `xemacs', you will be told how much pure space -you actually will need.) However, the advantage of preloading -additional files decreases as machines get faster. On modern machines, -it is often not advisable, especially if the Lisp code is on a file -system local to the machine running XEmacs. - - You can specify other Lisp expressions to execute just before dumping -by putting them in a library named `site-init.el'. However, if they -might alter the behavior that users expect from an ordinary unmodified -XEmacs, it is better to put them in `default.el', so that users can -override them if they wish. *Note Start-up Summary::. - - Before `loadup.el' dumps the new executable, it finds the -documentation strings for primitive and preloaded functions (and -variables) in the file where they are stored, by calling -`Snarf-documentation' (*note Accessing Documentation::.). These -strings were moved out of the `xemacs' executable to make it smaller. -*Note Documentation Basics::. - - - Function: dump-emacs TO-FILE FROM-FILE - This function dumps the current state of XEmacs into an executable - file TO-FILE. It takes symbols from FROM-FILE (this is normally - the executable file `temacs'). - - If you use this function in an XEmacs that was already dumped, you - must set `command-line-processed' to `nil' first for good results. - *Note Command Line Arguments::. - - - Function: run-emacs-from-temacs &rest ARGS - This is the function that implements the `run-temacs' command-line - argument. It is called from `loadup.el' as appropriate. You - should most emphatically *not* call this yourself; it will - reinitialize your XEmacs process and you'll be sorry. - - - Command: emacs-version - This function returns a string describing the version of XEmacs - that is running. It is useful to include this string in bug - reports. - - (emacs-version) - => "XEmacs 20.1 [Lucid] (i586-unknown-linux2.0.29) - of Mon Apr 7 1997 on altair.xemacs.org" - - Called interactively, the function prints the same information in - the echo area. - - - Variable: emacs-build-time - The value of this variable is the time at which XEmacs was built - at the local site. - - emacs-build-time "Mon Apr 7 20:28:52 1997" - => - - - Variable: emacs-version - The value of this variable is the version of Emacs being run. It - is a string, e.g. `"20.1 XEmacs Lucid"'. - - The following two variables did not exist before FSF GNU Emacs -version 19.23 and XEmacs version 19.10, which reduces their usefulness -at present, but we hope they will be convenient in the future. - - - Variable: emacs-major-version - The major version number of Emacs, as an integer. For XEmacs - version 20.1, the value is 20. - - - Variable: emacs-minor-version - The minor version number of Emacs, as an integer. For XEmacs - version 20.1, the value is 1. +File: lispref.info, Node: libpq Lisp Symbols and DataTypes, Next: Synchronous Interface Functions, Prev: libpq Lisp Variables, Up: XEmacs PostgreSQL libpq API - -File: lispref.info, Node: Pure Storage, Next: Garbage Collection, Prev: Building XEmacs, Up: Building XEmacs and Object Allocation - -Pure Storage -============ - - XEmacs Lisp uses two kinds of storage for user-created Lisp objects: -"normal storage" and "pure storage". Normal storage is where all the -new data created during an XEmacs session is kept; see the following -section for information on normal storage. Pure storage is used for -certain data in the preloaded standard Lisp files--data that should -never change during actual use of XEmacs. - - Pure storage is allocated only while `temacs' is loading the -standard preloaded Lisp libraries. In the file `xemacs', it is marked -as read-only (on operating systems that permit this), so that the -memory space can be shared by all the XEmacs jobs running on the machine -at once. Pure storage is not expandable; a fixed amount is allocated -when XEmacs is compiled, and if that is not sufficient for the preloaded -libraries, `temacs' aborts with an error message. If that happens, you -must increase the compilation parameter `PURESIZE' using the -`--puresize' option to `configure'. This normally won't happen unless -you try to preload additional libraries or add features to the standard -ones. - - - Function: purecopy OBJECT - This function makes a copy of OBJECT in pure storage and returns - it. It copies strings by simply making a new string with the same - characters in pure storage. It recursively copies the contents of - vectors and cons cells. It does not make copies of other objects - such as symbols, but just returns them unchanged. It signals an - error if asked to copy markers. - - This function is a no-op except while XEmacs is being built and - dumped; it is usually called only in the file - `xemacs/lisp/prim/loaddefs.el', but a few packages call it just in - case you decide to preload them. - - - Variable: pure-bytes-used - The value of this variable is the number of bytes of pure storage - allocated so far. Typically, in a dumped XEmacs, this number is - very close to the total amount of pure storage available--if it - were not, we would preallocate less. - - - Variable: purify-flag - This variable determines whether `defun' should make a copy of the - function definition in pure storage. If it is non-`nil', then the - function definition is copied into pure storage. - - This flag is `t' while loading all of the basic functions for - building XEmacs initially (allowing those functions to be sharable - and non-collectible). Dumping XEmacs as an executable always - writes `nil' in this variable, regardless of the value it actually - has before and after dumping. - - You should not change this flag in a running XEmacs. - - -File: lispref.info, Node: Garbage Collection, Prev: Pure Storage, Up: Building XEmacs and Object Allocation - -Garbage Collection -================== - - When a program creates a list or the user defines a new function -(such as by loading a library), that data is placed in normal storage. -If normal storage runs low, then XEmacs asks the operating system to -allocate more memory in blocks of 2k bytes. Each block is used for one -type of Lisp object, so symbols, cons cells, markers, etc., are -segregated in distinct blocks in memory. (Vectors, long strings, -buffers and certain other editing types, which are fairly large, are -allocated in individual blocks, one per object, while small strings are -packed into blocks of 8k bytes. [More correctly, a string is allocated -in two sections: a fixed size chunk containing the length, list of -extents, etc.; and a chunk containing the actual characters in the -string. It is this latter chunk that is either allocated individually -or packed into 8k blocks. The fixed size chunk is packed into 2k -blocks, as for conses, markers, etc.]) - - It is quite common to use some storage for a while, then release it -by (for example) killing a buffer or deleting the last pointer to an -object. XEmacs provides a "garbage collector" to reclaim this -abandoned storage. (This name is traditional, but "garbage recycler" -might be a more intuitive metaphor for this facility.) - - The garbage collector operates by finding and marking all Lisp -objects that are still accessible to Lisp programs. To begin with, it -assumes all the symbols, their values and associated function -definitions, and any data presently on the stack, are accessible. Any -objects that can be reached indirectly through other accessible objects -are also accessible. - - When marking is finished, all objects still unmarked are garbage. No -matter what the Lisp program or the user does, it is impossible to refer -to them, since there is no longer a way to reach them. Their space -might as well be reused, since no one will miss them. The second -("sweep") phase of the garbage collector arranges to reuse them. - - The sweep phase puts unused cons cells onto a "free list" for future -allocation; likewise for symbols, markers, extents, events, floats, -compiled-function objects, and the fixed-size portion of strings. It -compacts the accessible small string-chars chunks so they occupy fewer -8k blocks; then it frees the other 8k blocks. Vectors, buffers, -windows, and other large objects are individually allocated and freed -using `malloc' and `free'. - - Common Lisp note: unlike other Lisps, XEmacs Lisp does not call - the garbage collector when the free list is empty. Instead, it - simply requests the operating system to allocate more storage, and - processing continues until `gc-cons-threshold' bytes have been - used. - - This means that you can make sure that the garbage collector will - not run during a certain portion of a Lisp program by calling the - garbage collector explicitly just before it (provided that portion - of the program does not use so much space as to force a second - garbage collection). - - - Command: garbage-collect - This command runs a garbage collection, and returns information on - the amount of space in use. (Garbage collection can also occur - spontaneously if you use more than `gc-cons-threshold' bytes of - Lisp data since the previous garbage collection.) - - `garbage-collect' returns a list containing the following - information: - - ((USED-CONSES . FREE-CONSES) - (USED-SYMS . FREE-SYMS) - (USED-MARKERS . FREE-MARKERS) - USED-STRING-CHARS - USED-VECTOR-SLOTS - (PLIST)) - - => ((73362 . 8325) (13718 . 164) - (5089 . 5098) 949121 118677 - (conses-used 73362 conses-free 8329 cons-storage 658168 - symbols-used 13718 symbols-free 164 symbol-storage 335216 - bit-vectors-used 0 bit-vectors-total-length 0 - bit-vector-storage 0 vectors-used 7882 - vectors-total-length 118677 vector-storage 537764 - compiled-functions-used 1336 compiled-functions-free 37 - compiled-function-storage 44440 short-strings-used 28829 - long-strings-used 2 strings-free 7722 - short-strings-total-length 916657 short-string-storage 1179648 - long-strings-total-length 32464 string-header-storage 441504 - floats-used 3 floats-free 43 float-storage 2044 markers-used 5089 - markers-free 5098 marker-storage 245280 events-used 103 - events-free 835 event-storage 110656 extents-used 10519 - extents-free 2718 extent-storage 372736 - extent-auxiliarys-used 111 extent-auxiliarys-freed 3 - extent-auxiliary-storage 4440 window-configurations-used 39 - window-configurations-on-free-list 5 - window-configurations-freed 10 window-configuration-storage 9492 - popup-datas-used 3 popup-data-storage 72 toolbar-buttons-used 62 - toolbar-button-storage 4960 toolbar-datas-used 12 - toolbar-data-storage 240 symbol-value-buffer-locals-used 182 - symbol-value-buffer-local-storage 5824 - symbol-value-lisp-magics-used 22 - symbol-value-lisp-magic-storage 1496 - symbol-value-varaliases-used 43 - symbol-value-varalias-storage 1032 opaque-lists-used 2 - opaque-list-storage 48 color-instances-used 12 - color-instance-storage 288 font-instances-used 5 - font-instance-storage 180 opaques-used 11 opaque-storage 312 - range-tables-used 1 range-table-storage 16 faces-used 34 - face-storage 2584 glyphs-used 124 glyph-storage 4464 - specifiers-used 775 specifier-storage 43869 weak-lists-used 786 - weak-list-storage 18864 char-tables-used 40 - char-table-storage 41920 buffers-used 25 buffer-storage 7000 - extent-infos-used 457 extent-infos-freed 73 - extent-info-storage 9140 keymaps-used 275 keymap-storage 12100 - consoles-used 4 console-storage 384 command-builders-used 2 - command-builder-storage 120 devices-used 2 device-storage 344 - frames-used 3 frame-storage 624 image-instances-used 47 - image-instance-storage 3008 windows-used 27 windows-freed 2 - window-storage 9180 lcrecord-lists-used 15 - lcrecord-list-storage 360 hash-tables-used 631 - hash-table-storage 25240 streams-used 1 streams-on-free-list 3 - streams-freed 12 stream-storage 91)) - - Here is a table explaining each element: - - USED-CONSES - The number of cons cells in use. - - FREE-CONSES - The number of cons cells for which space has been obtained - from the operating system, but that are not currently being - used. - - USED-SYMS - The number of symbols in use. - - FREE-SYMS - The number of symbols for which space has been obtained from - the operating system, but that are not currently being used. - - USED-MARKERS - The number of markers in use. - - FREE-MARKERS - The number of markers for which space has been obtained from - the operating system, but that are not currently being used. - - USED-STRING-CHARS - The total size of all strings, in characters. - - USED-VECTOR-SLOTS - The total number of elements of existing vectors. - - PLIST - A list of alternating keyword/value pairs providing more - detailed information. (As you can see above, quite a lot of - information is provided.) - - - User Option: gc-cons-threshold - The value of this variable is the number of bytes of storage that - must be allocated for Lisp objects after one garbage collection in - order to trigger another garbage collection. A cons cell counts - as eight bytes, a string as one byte per character plus a few - bytes of overhead, and so on; space allocated to the contents of - buffers does not count. Note that the subsequent garbage - collection does not happen immediately when the threshold is - exhausted, but only the next time the Lisp evaluator is called. - - The initial threshold value is 500,000. If you specify a larger - value, garbage collection will happen less often. This reduces the - amount of time spent garbage collecting, but increases total - memory use. You may want to do this when running a program that - creates lots of Lisp data. - - You can make collections more frequent by specifying a smaller - value, down to 10,000. A value less than 10,000 will remain in - effect only until the subsequent garbage collection, at which time - `garbage-collect' will set the threshold back to 10,000. (This does - not apply if XEmacs was configured with `--debug'. Therefore, be - careful when setting `gc-cons-threshold' in that case!) - - - Function: memory-limit - This function returns the address of the last byte XEmacs has - allocated, divided by 1024. We divide the value by 1024 to make - sure it fits in a Lisp integer. - - You can use this to get a general idea of how your actions affect - the memory usage. - - - Variable: pre-gc-hook - This is a normal hook to be run just before each garbage - collection. Interrupts, garbage collection, and errors are - inhibited while this hook runs, so be extremely careful in what - you add here. In particular, avoid consing, and do not interact - with the user. - - - Variable: post-gc-hook - This is a normal hook to be run just after each garbage collection. - Interrupts, garbage collection, and errors are inhibited while - this hook runs, so be extremely careful in what you add here. In - particular, avoid consing, and do not interact with the user. - - - Variable: gc-message - This is a string to print to indicate that a garbage collection is - in progress. This is printed in the echo area. If the selected - frame is on a window system and `gc-pointer-glyph' specifies a - value (i.e. a pointer image instance) in the domain of the - selected frame, the mouse cursor will change instead of this - message being printed. - - - Glyph: gc-pointer-glyph - This holds the pointer glyph used to indicate that a garbage - collection is in progress. If the selected window is on a window - system and this glyph specifies a value (i.e. a pointer image - instance) in the domain of the selected window, the cursor will be - changed as specified during garbage collection. Otherwise, a - message will be printed in the echo area, as controlled by - `gc-message'. *Note Glyphs::. - - If XEmacs was configured with `--debug', you can set the following -two variables to get direct information about all the allocation that -is happening in a segment of Lisp code. - - - Variable: debug-allocation - If non-zero, print out information to stderr about all objects - allocated. - - - Variable: debug-allocation-backtrace - Length (in stack frames) of short backtrace printed out by - `debug-allocation'. - - -File: lispref.info, Node: Standard Errors, Next: Standard Buffer-Local Variables, Prev: Building XEmacs and Object Allocation, Up: Top - -Standard Errors -*************** - - Here is the complete list of the error symbols in standard Emacs, -grouped by concept. The list includes each symbol's message (on the -`error-message' property of the symbol) and a cross reference to a -description of how the error can occur. - - Each error symbol has an `error-conditions' property that is a list -of symbols. Normally this list includes the error symbol itself and -the symbol `error'. Occasionally it includes additional symbols, which -are intermediate classifications, narrower than `error' but broader -than a single error symbol. For example, all the errors in accessing -files have the condition `file-error'. - - As a special exception, the error symbol `quit' does not have the -condition `error', because quitting is not considered an error. - - *Note Errors::, for an explanation of how errors are generated and -handled. - -`SYMBOL' - STRING; REFERENCE. - -`error' - `"error"' - *Note Errors::. - -`quit' - `"Quit"' - *Note Quitting::. - -`args-out-of-range' - `"Args out of range"' - *Note Sequences Arrays Vectors::. - -`arith-error' - `"Arithmetic error"' - See `/' and `%' in *Note Numbers::. - -`beginning-of-buffer' - `"Beginning of buffer"' - *Note Motion::. - -`buffer-read-only' - `"Buffer is read-only"' - *Note Read Only Buffers::. - -`cyclic-function-indirection' - `"Symbol's chain of function indirections contains a loop"' - *Note Function Indirection::. - -`domain-error' - `"Arithmetic domain error"' -`end-of-buffer' - `"End of buffer"' - *Note Motion::. - -`end-of-file' - `"End of file during parsing"' - This is not a `file-error'. - *Note Input Functions::. - -`file-error' - This error and its subcategories do not have error-strings, - because the error message is constructed from the data items alone - when the error condition `file-error' is present. - *Note Files::. - -`file-locked' - This is a `file-error'. - *Note File Locks::. - -`file-already-exists' - This is a `file-error'. - *Note Writing to Files::. - -`file-supersession' - This is a `file-error'. - *Note Modification Time::. - -`invalid-byte-code' - `"Invalid byte code"' - *Note Byte Compilation::. - -`invalid-function' - `"Invalid function"' - *Note Classifying Lists::. - -`invalid-read-syntax' - `"Invalid read syntax"' - *Note Input Functions::. - -`invalid-regexp' - `"Invalid regexp"' - *Note Regular Expressions::. - -`mark-inactive' - `"The mark is not active now"' -`no-catch' - `"No catch for tag"' - *Note Catch and Throw::. - -`overflow-error' - `"Arithmetic overflow error"' -`protected-field' - `"Attempt to modify a protected field"' -`range-error' - `"Arithmetic range error"' -`search-failed' - `"Search failed"' - *Note Searching and Matching::. - -`setting-constant' - `"Attempt to set a constant symbol"' - *Note Variables that Never Change: Constant Variables. - -`singularity-error' - `"Arithmetic singularity error"' -`tooltalk-error' - `"ToolTalk error"' - *Note ToolTalk Support::. - -`undefined-keystroke-sequence' - `"Undefined keystroke sequence"' -`void-function' - `"Symbol's function definition is void"' - *Note Function Cells::. - -`void-variable' - `"Symbol's value as variable is void"' - *Note Accessing Variables::. - -`wrong-number-of-arguments' - `"Wrong number of arguments"' - *Note Classifying Lists::. - -`wrong-type-argument' - `"Wrong type argument"' - *Note Type Predicates::. - - These error types, which are all classified as special cases of -`arith-error', can occur on certain systems for invalid use of -mathematical functions. - -`domain-error' - `"Arithmetic domain error"' - *Note Math Functions::. - -`overflow-error' - `"Arithmetic overflow error"' - *Note Math Functions::. - -`range-error' - `"Arithmetic range error"' - *Note Math Functions::. - -`singularity-error' - `"Arithmetic singularity error"' - *Note Math Functions::. - -`underflow-error' - `"Arithmetic underflow error"' - *Note Math Functions::. - - -File: lispref.info, Node: Standard Buffer-Local Variables, Next: Standard Keymaps, Prev: Standard Errors, Up: Top - -Buffer-Local Variables -********************** - - The table below lists the general-purpose Emacs variables that are -automatically local (when set) in each buffer. Many Lisp packages -define such variables for their internal use; we don't list them here. - -`abbrev-mode' - *note Abbrevs::. - -`auto-fill-function' - *note Auto Filling::. - -`buffer-auto-save-file-name' - *note Auto-Saving::. - -`buffer-backed-up' - *note Backup Files::. - -`buffer-display-table' - *note Display Tables::. - -`buffer-file-format' - *note Format Conversion::. - -`buffer-file-name' - *note Buffer File Name::. - -`buffer-file-number' - *note Buffer File Name::. - -`buffer-file-truename' - *note Buffer File Name::. - -`buffer-file-type' - *note Files and MS-DOS::. - -`buffer-invisibility-spec' - *note Invisible Text::. - -`buffer-offer-save' - *note Saving Buffers::. - -`buffer-read-only' - *note Read Only Buffers::. - -`buffer-saved-size' - *note Point::. - -`buffer-undo-list' - *note Undo::. - -`cache-long-line-scans' - *note Text Lines::. - -`case-fold-search' - *note Searching and Case::. +libpq Lisp Symbols and Datatypes +-------------------------------- -`ctl-arrow' - *note Usual Display::. + The following set of symbols are used to represent the intermediate +states involved in the asynchronous interface. -`comment-column' - *note Comments: (emacs)Comments. + - Symbol: pgres::polling-failed + Undocumented. A fatal error has occurred during processing of an + asynchronous operation. -`default-directory' - *note System Environment::. + - Symbol: pgres::polling-reading + An intermediate status return during an asynchronous operation. It + indicates that one may use `select' before polling again. -`defun-prompt-regexp' - *note List Motion::. + - Symbol: pgres::polling-writing + An intermediate status return during an asynchronous operation. It + indicates that one may use `select' before polling again. -`fill-column' - *note Auto Filling::. + - Symbol: pgres::polling-ok + An asynchronous operation has successfully completed. -`goal-column' - *note Moving Point: (emacs)Moving Point. + - Symbol: pgres::polling-active + An intermediate status return during an asynchronous operation. + One can call the poll function again immediately. -`left-margin' - *note Indentation::. + - Function: pq-pgconn conn field + CONN A database connection object. FIELD A symbol indicating + which field of PGconn to fetch. Possible values are shown in the + following table. + `pq::db' + Database name -`local-abbrev-table' - *note Abbrevs::. + `pq::user' + Database user name -`local-write-file-hooks' - *note Saving Buffers::. + `pq::pass' + Database user's password -`major-mode' - *note Mode Help::. + `pq::host' + Hostname database server is running on -`mark-active' - *note The Mark::. + `pq::port' + TCP port number used in the connection -`mark-ring' - *note The Mark::. + `pq::tty' + Debugging TTY -`minor-modes' - *note Minor Modes::. + Compatibility note: Debugging TTYs are not used in the + XEmacs Lisp API. -`modeline-format' - *note Modeline Data::. + `pq::options' + Additional server options -`modeline-buffer-identification' - *note Modeline Variables::. + `pq::status' + Connection status. Possible return values are shown in the + following table. + `pg::connection-ok' + The normal, connected status. -`modeline-format' - *note Modeline Data::. + `pg::connection-bad' + The connection is not open and the PGconn object needs + to be deleted by `pq-finish'. -`modeline-modified' - *note Modeline Variables::. + `pg::connection-started' + An asynchronous connection has been started, but is not + yet complete. -`modeline-process' - *note Modeline Variables::. + `pg::connection-made' + An asynchronous connect has been made, and there is data + waiting to be sent. -`mode-name' - *note Modeline Variables::. + `pg::connection-awaiting-response' + Awaiting data from the backend during an asynchronous + connection. -`overwrite-mode' - *note Insertion::. + `pg::connection-auth-ok' + Received authentication, waiting for the backend to + start up. -`paragraph-separate' - *note Standard Regexps::. + `pg::connection-setenv' + Negotiating environment during an asynchronous + connection. -`paragraph-start' - *note Standard Regexps::. + `pq::error-message' + The last error message that was delivered to this connection. -`point-before-scroll' - Used for communication between mouse commands and scroll-bar - commands. + `pq::backend-pid' + The process ID of the backend database server. -`require-final-newline' - *note Insertion::. + The `PGresult' object is used by libpq to encapsulate the results of +queries. The printed representation takes on four forms. When the +PGresult object contains tuples from an SQL `SELECT' it will look like: -`selective-display' - *note Selective Display::. + (setq R (pq-exec P "SELECT * FROM xemacs_test;")) + => # -`selective-display-ellipses' - *note Selective Display::. + The number in brackets indicates how many rows of data are available. +When the PGresult object is the result of a command query that doesn't +return anything, it will look like: -`tab-width' - *note Usual Display::. + (pq-exec P "CREATE TABLE a_new_table (i int);") + => # -`truncate-lines' - *note Truncation::. - -`vc-mode' - *note Modeline Variables::. + When either the query is a command-type query that can affect a +number of different rows, but doesn't return any of them it will look +like: + + (progn + (pq-exec P "INSERT INTO a_new_table VALUES (1);") + (pq-exec P "INSERT INTO a_new_table VALUES (2);") + (pq-exec P "INSERT INTO a_new_table VALUES (3);") + (setq R (pq-exec P "DELETE FROM a_new_table;"))) + => # + + Lastly, when the underlying PGresult object has been deallocated +directly by `pq-clear' the printed representation will look like: + + (progn + (setq R (pq-exec P "SELECT * FROM xemacs_test;")) + (pq-clear R) + R) + => # + + The following set of functions are accessors to various data in the +PGresult object. + + - Function: pq-result-status result + Return status of a query result. RESULT is a PGresult object. + The return value is one of the symbols in the following table. + `pgres::empty-query' + A query contained no text. This is usually the result of a + recoverable error, or a minor programming error. + + `pgres::command-ok' + A query command that doesn't return anything was executed + properly by the backend. + + `pgres::tuples-ok' + A query command that returns tuples was executed properly by + the backend. + + `pgres::copy-out' + Copy Out data transfer is in progress. + + `pgres::copy-in' + Copy In data transfer is in progress. + + `pgres::bad-response' + An unexpected response was received from the backend. + + `pgres::nonfatal-error' + Undocumented. This value is returned when the libpq function + `PQresultStatus' is called with a NULL pointer. + + `pgres::fatal-error' + Undocumented. An error has occurred in processing the query + and the operation was not completed. + + - Function: pq-res-status result + Return the query result status as a string, not a symbol. RESULT + is a PGresult object. + + (setq R (pq-exec P "SELECT * FROM xemacs_test;")) + => # + (pq-res-status R) + => "PGRES_TUPLES_OK" + + - Function: pq-result-error-message result + Return an error message generated by the query, if any. RESULT is + a PGresult object. + + (setq R (pq-exec P "SELECT * FROM xemacs-test;")) + => + (pq-result-error-message R) + => "ERROR: parser: parse error at or near \"-\" + " + + - Function: pq-ntuples result + Return the number of tuples in the query result. RESULT is a + PGresult object. + + (setq R (pq-exec P "SELECT * FROM xemacs_test;")) + => # + (pq-ntuples R) + => 5 + + - Function: pq-nfields result + Return the number of fields in each tuple of the query result. + RESULT is a PGresult object. + + (setq R (pq-exec P "SELECT * FROM xemacs_test;")) + => # + (pq-nfields R) + => 3 + + - Function: pq-binary-tuples result + Returns t if binary tuples are present in the results, nil + otherwise. RESULT is a PGresult object. + + (setq R (pq-exec P "SELECT * FROM xemacs_test;")) + => # + (pq-binary-tuples R) + => nil + + - Function: pq-fname result field-index + Returns the name of a specific field. RESULT is a PGresult object. + FIELD-INDEX is the number of the column to select from. The first + column is number zero. + + (let (i l) + (setq R (pq-exec P "SELECT * FROM xemacs_test;")) + (setq i (pq-nfields R)) + (while (>= (decf i) 0) + (push (pq-fname R i) l)) + l) + => ("id" "shikona" "rank") + + - Function: pq-fnumber result field-name + Return the field number corresponding to the given field name. -1 + is returned on a bad field name. RESULT is a PGresult object. + FIELD-NAME is a string representing the field name to find. + (setq R (pq-exec P "SELECT * FROM xemacs_test;")) + => # + (pq-fnumber R "id") + => 0 + (pq-fnumber R "Not a field") + => -1 + + - Function: pq-ftype result field-num + Return an integer code representing the data type of the specified + column. RESULT is a PGresult object. FIELD-NUM is the field + number. + + The return value of this function is the Object ID (Oid) in the + database of the type. Further queries need to be made to various + system tables in order to convert this value into something useful. + + - Function: pq-fmod result field-num + Return the type modifier code associated with a field. Field + numbers start at zero. RESULT is a PGresult object. FIELD-INDEX + selects which field to use. + + - Function: pq-fsize result field-index + Return size of the given field. RESULT is a PGresult object. + FIELD-INDEX selects which field to use. + + (let (i l) + (setq R (pq-exec P "SELECT * FROM xemacs_test;")) + (setq i (pq-nfields R)) + (while (>= (decf i) 0) + (push (list (pq-ftype R i) (pq-fsize R i)) l)) + l) + => ((23 23) (25 25) (25 25)) + + - Function: pq-get-value result tup-num field-num + Retrieve a return value. RESULT is a PGresult object. TUP-NUM + selects which tuple to fetch from. FIELD-NUM selects which field + to fetch from. + + Both tuples and fields are numbered from zero. + + (setq R (pq-exec P "SELECT * FROM xemacs_test;")) + => # + (pq-get-value R 0 1) + => "Musashimaru" + (pq-get-value R 1 1) + => "Dejima" + (pq-get-value R 2 1) + => "Musoyama" + + - Function: pq-get-length result tup-num field-num + Return the length of a specific value. RESULT is a PGresult + object. TUP-NUM selects which tuple to fetch from. FIELD-NUM + selects which field to fetch from. + + (setq R (pq-exec P "SELECT * FROM xemacs_test;")) + => # + (pq-get-length R 0 1) + => 11 + (pq-get-length R 1 1) + => 6 + (pq-get-length R 2 1) + => 8 + + - Function: pq-get-is-null result tup-num field-num + Return t if the specific value is the SQL NULL. RESULT is a + PGresult object. TUP-NUM selects which tuple to fetch from. + FIELD-NUM selects which field to fetch from. + + - Function: pq-cmd-status result + Return a summary string from the query. RESULT is a PGresult + object. + (pq-exec P "INSERT INTO xemacs_test + VALUES (6, 'Wakanohana', 'Yokozuna');") + => # + (pq-cmd-status R) + => "INSERT 542086 1" + (setq R (pq-exec P "UPDATE xemacs_test SET rank='retired' + WHERE shikona='Wakanohana';")) + => # + (pq-cmd-status R) + => "UPDATE 1" + + Note that the first number returned from an insertion, like in the + example, is an object ID number and will almost certainly vary from + system to system since object ID numbers in Postgres must be unique + across all databases. + + - Function: pq-cmd-tuples result + Return the number of tuples if the last command was an + INSERT/UPDATE/DELETE. If the last command was something else, the + empty string is returned. RESULT is a PGresult object. + + (setq R (pq-exec P "INSERT INTO xemacs_test VALUES + (7, 'Takanohana', 'Yokuzuna');")) + => # + (pq-cmd-tuples R) + => "1" + (setq R (pq-exec P "SELECT * from xemacs_test;")) + => # + (pq-cmd-tuples R) + => "" + (setq R (pq-exec P "DELETE FROM xemacs_test + WHERE shikona LIKE '%hana';")) + => # + (pq-cmd-tuples R) + => "2" + + - Function: pq-oid-value result + Return the object id of the insertion if the last command was an + INSERT. 0 is returned if the last command was not an insertion. + RESULT is a PGresult object. + + In the first example, the numbers you will see on your local + system will almost certainly be different, however the second + number from the right in the unprintable PGresult object and the + number returned by `pq-oid-value' should match. + (setq R (pq-exec P "INSERT INTO xemacs_test VALUES + (8, 'Terao', 'Maegashira');")) + => # + (pq-oid-value R) + => 542089 + (setq R (pq-exec P "SELECT shikona FROM xemacs_test + WHERE rank='Maegashira';")) + => # + (pq-oid-value R) + => 0 + + - Function: pq-make-empty-pgresult conn status + Create an empty pgresult with the given status. CONN a database + connection object STATUS a value that can be returned by + `pq-result-status'. + + The caller is responsible for making sure the return value gets + properly freed.  -File: lispref.info, Node: Standard Keymaps, Next: Standard Hooks, Prev: Standard Buffer-Local Variables, Up: Top - -Standard Keymaps -**************** - - The following symbols are used as the names for various keymaps. -Some of these exist when XEmacs is first started, others are loaded -only when their respective mode is used. This is not an exhaustive -list. - - Almost all of these maps are used as local maps. Indeed, of the -modes that presently exist, only Vip mode and Terminal mode ever change -the global keymap. - -`bookmark-map' - A keymap containing bindings to bookmark functions. - -`Buffer-menu-mode-map' - A keymap used by Buffer Menu mode. - -`c++-mode-map' - A keymap used by C++ mode. - -`c-mode-map' - A keymap used by C mode. A sparse keymap used by C mode. - -`command-history-map' - A keymap used by Command History mode. - -`ctl-x-4-map' - A keymap for subcommands of the prefix `C-x 4'. - -`ctl-x-5-map' - A keymap for subcommands of the prefix `C-x 5'. - -`ctl-x-map' - A keymap for `C-x' commands. - -`debugger-mode-map' - A keymap used by Debugger mode. - -`dired-mode-map' - A keymap for `dired-mode' buffers. - -`edit-abbrevs-map' - A keymap used in `edit-abbrevs'. - -`edit-tab-stops-map' - A keymap used in `edit-tab-stops'. - -`electric-buffer-menu-mode-map' - A keymap used by Electric Buffer Menu mode. - -`electric-history-map' - A keymap used by Electric Command History mode. - -`emacs-lisp-mode-map' - A keymap used by Emacs Lisp mode. - -`help-map' - A keymap for characters following the Help key. - -`Helper-help-map' - A keymap used by the help utility package. - It has the same keymap in its value cell and in its function cell. - -`Info-edit-map' - A keymap used by the `e' command of Info. - -`Info-mode-map' - A keymap containing Info commands. - -`isearch-mode-map' - A keymap that defines the characters you can type within - incremental search. - -`itimer-edit-map' - A keymap used when in Itimer Edit mode. - -`lisp-interaction-mode-map' - A keymap used by Lisp mode. - -`lisp-mode-map' - A keymap used by Lisp mode. +File: lispref.info, Node: Synchronous Interface Functions, Next: Asynchronous Interface Functions, Prev: libpq Lisp Symbols and DataTypes, Up: XEmacs PostgreSQL libpq API + +Synchronous Interface Functions +------------------------------- + + - Function: pq-connectdb conninfo + Establish a (synchronous) database connection. CONNINFO A string + of blank separated options. Options are of the form "OPTION = + VALUE". If VALUE contains blanks, it must be single quoted. + Blanks around the equal sign are optional. Multiple option + assignments are blank separated. + (pq-connectdb "dbname=japanese port = 25432") + => # + The printed representation of a database connection object has four + fields. The first field is the hostname where the database server + is running (in this case localhost), the second field is the port + number, the third field is the database user name, and the fourth + field is the name of the database. + + Database connection objects which have been disconnected and will + generate an immediate error if they are used look like: + # + Bad connections can be reestablished with `pq-reset', or deleted + entirely with `pq-finish'. + + A database connection object that has been deleted looks like: + (let ((P1 (pq-connectdb ""))) + (pq-finish P1) + P1) + => # + + Note that database connection objects are the most heavy weight + objects in XEmacs Lisp at this writing, usually representing as + much as several megabytes of virtual memory on the machine the + database server is running on. It is wisest to explicitly delete + them when you are finished with them, rather than letting garbage + collection do it. An example idiom is: + + (let ((P (pq-connectiondb ""))) + (unwind-protect + (progn + (...)) ; access database here + (pq-finish P))) + + The following options are available in the options string: + `authtype' + Authentication type. Same as PGAUTHTYPE. This is no longer + used. - A keymap for minibuffer input with completion. + `user' + Database user name. Same as PGUSER. -`minibuffer-local-isearch-map' - A keymap for editing isearch strings in the minibuffer. + `password' + Database password. -`minibuffer-local-map' - Default keymap to use when reading from the minibuffer. + `dbname' + Database name. Same as PGDATABASE -`minibuffer-local-must-match-map' - A keymap for minibuffer input with completion, for exact match. + `host' + Symbolic hostname. Same as PGHOST. -`mode-specific-map' - The keymap for characters following `C-c'. Note, this is in the - global map. This map is not actually mode specific: its name was - chosen to be informative for the user in `C-h b' - (`display-bindings'), where it describes the main use of the `C-c' - prefix key. + `hostaddr' + Host address as four octets (eg. like 192.168.1.1). -`modeline-map' - The keymap consulted for mouse-clicks on the modeline of a window. + `port' + TCP port to connect to. Same as PGPORT. -`objc-mode-map' - A keymap used in Objective C mode as a local map. + `tty' + Debugging TTY. Same as PGTTY. This value is suppressed in + the XEmacs Lisp API. -`occur-mode-map' - A local keymap used by Occur mode. + `options' + Extra backend database options. Same as PGOPTIONS. A + database connection object is returned regardless of whether a + connection was established or not. -`overriding-local-map' - A keymap that overrides all other local keymaps. + - Function: pq-reset conn + Reestablish database connection. CONN A database connection + object. -`query-replace-map' - A local keymap used for responses in `query-replace' and related - commands; also for `y-or-n-p' and `map-y-or-n-p'. The functions - that use this map do not support prefix keys; they look up one - event at a time. + This function reestablishes a database connection using the + original connection parameters. This is useful if something has + happened to the TCP link and it has become broken. -`read-expression-map' - The minibuffer keymap used for reading Lisp expressions. + - Function: pq-exec conn query + Make a synchronous database query. CONN A database connection + object. QUERY A string containing an SQL query. A PGresult + object is returned, which in turn may be queried by its many + accessor functions to retrieve state out of it. If the query + string contains multiple SQL commands, only results from the final + command are returned. -`read-shell-command-map' - The minibuffer keymap used by shell-command and related commands. + (setq R (pq-exec P "SELECT * FROM xemacs_test; + DELETE FROM xemacs_test WHERE id=8;")) + => # -`shared-lisp-mode-map' - A keymap for commands shared by all sorts of Lisp modes. + - Function: pq-notifies conn + Return the latest async notification that has not yet been handled. + CONN A database connection object. If there has been a + notification, then a list of two elements will be returned. The + first element contains the relation name being notified, the second + element contains the backend process ID number. nil is returned + if there aren't any notifications to process. -`text-mode-map' - A keymap used by Text mode. + - Function: PQsetenv conn + Synchronous transfer of environment variables to a backend CONN A + database connection object. -`toolbar-map' - The keymap consulted for mouse-clicks over a toolbar. + Environment variable transfer is done as a normal part of database + connection. -`view-mode-map' - A keymap used by View mode. + Compatibility note: This function was present but not documented + in versions of libpq prior to 7.0.  -File: lispref.info, Node: Standard Hooks, Next: Index, Prev: Standard Keymaps, Up: Top - -Standard Hooks -************** - - The following is a list of hook variables that let you provide -functions to be called from within Emacs on suitable occasions. - - Most of these variables have names ending with `-hook'. They are -"normal hooks", run by means of `run-hooks'. The value of such a hook -is a list of functions. The recommended way to put a new function on -such a hook is to call `add-hook'. *Note Hooks::, for more information -about using hooks. - - The variables whose names end in `-function' have single functions -as their values. Usually there is a specific reason why the variable is -not a normal hook, such as the need to pass arguments to the function. -(In older Emacs versions, some of these variables had names ending in -`-hook' even though they were not normal hooks.) - - The variables whose names end in `-hooks' or `-functions' have lists -of functions as their values, but these functions are called in a -special way (they are passed arguments, or else their values are used). - -`activate-menubar-hook' - -`activate-popup-menu-hook' - -`ad-definition-hooks' - -`adaptive-fill-function' - -`add-log-current-defun-function' - -`after-change-functions' - -`after-delete-annotation-hook' - -`after-init-hook' - -`after-insert-file-functions' - -`after-revert-hook' - -`after-save-hook' - -`after-set-visited-file-name-hooks' - -`after-write-file-hooks' - -`auto-fill-function' - -`auto-save-hook' - -`before-change-functions' - -`before-delete-annotation-hook' - -`before-init-hook' - -`before-revert-hook' - -`blink-paren-function' - -`buffers-menu-switch-to-buffer-function' - -`c++-mode-hook' - -`c-delete-function' - -`c-mode-common-hook' - -`c-mode-hook' - -`c-special-indent-hook' - -`calendar-load-hook' - -`change-major-mode-hook' - -`command-history-hook' - -`comment-indent-function' - -`compilation-buffer-name-function' - -`compilation-exit-message-function' - -`compilation-finish-function' - -`compilation-parse-errors-function' - -`compilation-mode-hook' - -`create-console-hook' - -`create-device-hook' - -`create-frame-hook' - -`dabbrev-friend-buffer-function' - -`dabbrev-select-buffers-function' - -`delete-console-hook' - -`delete-device-hook' - -`delete-frame-hook' - -`deselect-frame-hook' - -`diary-display-hook' - -`diary-hook' - -`dired-after-readin-hook' - -`dired-before-readin-hook' - -`dired-load-hook' - -`dired-mode-hook' - -`disabled-command-hook' - -`display-buffer-function' - -`ediff-after-setup-control-frame-hook' - -`ediff-after-setup-windows-hook' - -`ediff-before-setup-control-frame-hook' - -`ediff-before-setup-windows-hook' - -`ediff-brief-help-message-function' - -`ediff-cleanup-hook' +File: lispref.info, Node: Asynchronous Interface Functions, Next: Large Object Support, Prev: Synchronous Interface Functions, Up: XEmacs PostgreSQL libpq API -`ediff-control-frame-position-function' +Asynchronous Interface Functions +-------------------------------- -`ediff-display-help-hook' + Making command by command examples is too complex with the +asynchronous interface functions. See the examples section for +complete calling sequences. -`ediff-focus-on-regexp-matches-function' + - Function: pq-connect-start conninfo + Begin establishing an asynchronous database connection. CONNINFO + A string containing the connection options. See the documentation + of `pq-connectdb' for a listing of all the available flags. -`ediff-forward-word-function' + - Function: pq-connect-poll conn + An intermediate function to be called during an asynchronous + database connection. CONN A database connection object. The + result codes are documented in a previous section. -`ediff-hide-regexp-matches-function' + - Function: pq-is-busy conn + Returns t if `pq-get-result' would block waiting for input. CONN + A database connection object. -`ediff-keymap-setup-hook' + - Function: pq-consume-input conn + Consume any available input from the backend. CONN A database + connection object. -`ediff-load-hook' + Nil is returned if anything bad happens. -`ediff-long-help-message-function' + - Function: pq-reset-start conn + Reset connection to the backend asynchronously. CONN A database + connection object. -`ediff-make-wide-display-function' + - Function: pq-reset-poll conn + Poll an asynchronous reset for completion CONN A database + connection object. -`ediff-merge-split-window-function' + - Function: pq-reset-cancel conn + Attempt to request cancellation of the current operation. CONN A + database connection object. -`ediff-meta-action-function' + The return value is t if the cancel request was successfully + dispatched, nil if not (in which case conn->errorMessage is set). + Note: successful dispatch is no guarantee that there will be any + effect at the backend. The application must read the operation + result as usual. -`ediff-meta-redraw-function' + - Function: pq-send-query conn query + Submit a query to Postgres and don't wait for the result. CONN A + database connection object. Returns: t if successfully submitted + nil if error (conn->errorMessage is set) -`ediff-mode-hook' + - Function: pq-get-result conn + Retrieve an asynchronous result from a query. CONN A database + connection object. -`ediff-prepare-buffer-hook' + `nil' is returned when no more query work remains. -`ediff-quit-hook' + - Function: pq-set-nonblocking conn arg + Sets the PGconn's database connection non-blocking if the arg is + TRUE or makes it non-blocking if the arg is FALSE, this will not + protect you from PQexec(), you'll only be safe when using the + non-blocking API. CONN A database connection object. -`ediff-registry-setup-hook' + - Function: pq-is-nonblocking conn + Return the blocking status of the database connection CONN A + database connection object. -`ediff-select-hook' + - Function: pq-flush conn + Force the write buffer to be written (or at least try) CONN A + database connection object. -`ediff-session-action-function' + - Function: PQsetenvStart conn + Start asynchronously passing environment variables to a backend. + CONN A database connection object. -`ediff-session-group-setup-hook' + Compatibility note: this function is only available with libpq-7.0. -`ediff-setup-diff-regions-function' + - Function: PQsetenvPoll conn + Check an asynchronous environment variables transfer for + completion. CONN A database connection object. -`ediff-show-registry-hook' + Compatibility note: this function is only available with libpq-7.0. -`ediff-show-session-group-hook' + - Function: PQsetenvAbort conn + Attempt to terminate an asynchronous environment variables + transfer. CONN A database connection object. -`ediff-skip-diff-region-function' + Compatibility note: this function is only available with libpq-7.0. -`ediff-split-window-function' - -`ediff-startup-hook' - -`ediff-suspend-hook' - -`ediff-toggle-read-only-function' - -`ediff-unselect-hook' - -`ediff-window-setup-function' - -`edit-picture-hook' - -`electric-buffer-menu-mode-hook' - -`electric-command-history-hook' - -`electric-help-mode-hook' - -`emacs-lisp-mode-hook' - -`fill-paragraph-function' - -`find-file-hooks' - -`find-file-not-found-hooks' - -`first-change-hook' - -`font-lock-after-fontify-buffer-hook' - -`font-lock-beginning-of-syntax-function' - -`font-lock-mode-hook' - -`fume-found-function-hook' - -`fume-list-mode-hook' - -`fume-rescan-buffer-hook' - -`fume-sort-function' - -`gnus-startup-hook' - -`hack-local-variables-hook' - -`highlight-headers-follow-url-function' - -`hyper-apropos-mode-hook' - -`indent-line-function' - -`indent-mim-hook' - -`indent-region-function' - -`initial-calendar-window-hook' - -`isearch-mode-end-hook' - -`isearch-mode-hook' - -`java-mode-hook' - -`kill-buffer-hook' - -`kill-buffer-query-functions' - -`kill-emacs-hook' - -`kill-emacs-query-functions' - -`kill-hooks' - -`LaTeX-mode-hook' - -`latex-mode-hook' - -`ledit-mode-hook' - -`lisp-indent-function' - -`lisp-interaction-mode-hook' - -`lisp-mode-hook' - -`list-diary-entries-hook' - -`load-read-function' - -`log-message-filter-function' - -`m2-mode-hook' - -`mail-citation-hook' - -`mail-mode-hook' - -`mail-setup-hook' - -`make-annotation-hook' - -`makefile-mode-hook' - -`map-frame-hook' - -`mark-diary-entries-hook' - -`medit-mode-hook' - -`menu-no-selection-hook' - -`mh-compose-letter-hook' - -`mh-folder-mode-hook' - -`mh-letter-mode-hook' - -`mim-mode-hook' - -`minibuffer-exit-hook' - -`minibuffer-setup-hook' - -`mode-motion-hook' - -`mouse-enter-frame-hook' - -`mouse-leave-frame-hook' - -`mouse-track-cleanup-hook' - -`mouse-track-click-hook' - -`mouse-track-down-hook' - -`mouse-track-drag-hook' - -`mouse-track-drag-up-hook' - -`mouse-track-up-hook' - -`mouse-yank-function' - -`news-mode-hook' - -`news-reply-mode-hook' - -`news-setup-hook' - -`nongregorian-diary-listing-hook' - -`nongregorian-diary-marking-hook' - -`nroff-mode-hook' - -`objc-mode-hook' - -`outline-mode-hook' - -`perl-mode-hook' - -`plain-TeX-mode-hook' - -`post-command-hook' - -`post-gc-hook' - -`pre-abbrev-expand-hook' - -`pre-command-hook' - -`pre-display-buffer-function' - -`pre-gc-hook' - -`pre-idle-hook' - -`print-diary-entries-hook' - -`prolog-mode-hook' - -`protect-innocence-hook' - -`remove-message-hook' - -`revert-buffer-function' - -`revert-buffer-insert-contents-function' - -`rmail-edit-mode-hook' - -`rmail-mode-hook' - -`rmail-retry-setup-hook' - -`rmail-summary-mode-hook' - -`scheme-indent-hook' - -`scheme-mode-hook' - -`scribe-mode-hook' - -`select-frame-hook' - -`send-mail-function' - -`shell-mode-hook' - -`shell-set-directory-error-hook' + +File: lispref.info, Node: Large Object Support, Next: Other libpq Functions, Prev: Asynchronous Interface Functions, Up: XEmacs PostgreSQL libpq API -`special-display-function' +Large Object Support +-------------------- -`suspend-hook' + - Function: pq-lo-import conn filename + Import a file as a large object into the database. CONN a + database connection object FILENAME filename to import -`suspend-resume-hook' + On success, the object id is returned. -`temp-buffer-show-function' + - Function: pq-lo-export conn oid filename + Copy a large object in the database into a file. CONN a database + connection object. OID object id number of a large object. + FILENAME filename to export to. -`term-setup-hook' + +File: lispref.info, Node: Other libpq Functions, Next: Unimplemented libpq Functions, Prev: Large Object Support, Up: XEmacs PostgreSQL libpq API + +Other libpq Functions +--------------------- + + - Function: pq-finish conn + Destroy a database connection object by calling free on it. CONN + a database connection object + + It is possible to not call this routine because the usual XEmacs + garbage collection mechanism will call the underlying libpq + routine whenever it is releasing stale `PGconn' objects. However, + this routine is useful in `unwind-protect' clauses to make + connections go away quickly when unrecoverable errors have + occurred. + + After calling this routine, the printed representation of the + XEmacs wrapper object will contain the string "DEAD". + + - Function: pq-client-encoding conn + Return the client encoding as an integer code. CONN a database + connection object + + (pq-client-encoding P) + => 1 + + Compatibility note: This function did not exist prior to libpq-7.0 + and does not exist in a non-Mule XEmacs. + + - Function: pq-set-client-encoding conn encoding + Set client coding system. CONN a database connection object + ENCODING a string representing the desired coding system + + (pq-set-client-encoding P "EUC_JP") + => 0 + + The current idiom for ensuring proper coding system conversion is + the following (illustrated for EUC Japanese encoding): + (setq P (pq-connectdb "...")) + (let ((file-name-coding-system 'euc-jp) + (pg-coding-system 'euc-jp)) + (pq-set-client-encoding "EUC_JP") + ...) + (pq-finish P) + Compatibility note: This function did not exist prior to libpq-7.0 + and does not exist in a non-Mule XEmacs. + + - Function: pq-env-2-encoding + Return the integer code representing the coding system in + PGCLIENTENCODING. + + (pq-env-2-encoding) + => 0 + Compatibility note: This function did not exist prior to libpq-7.0 + and does not exist in a non-Mule XEmacs. + + - Function: pq-clear res + Destroy a query result object by calling free() on it. RES a + query result object + + Note: The memory allocation systems of libpq and XEmacs are + different. The XEmacs representation of a query result object + will have both the XEmacs version and the libpq version freed at + the next garbage collection when the object is no longer being + referenced. Calling this function does not release the XEmacs + object, it is still subject to the usual rules for Lisp objects. + The printed representation of the XEmacs object will contain the + string "DEAD" after this routine is called indicating that it is no + longer useful for anything. + + - Function: pq-conn-defaults + Return a data structure that represents the connection defaults. + The data is returned as a list of lists, where each sublist + contains info regarding a single option. -`terminal-mode-hook' + +File: lispref.info, Node: Unimplemented libpq Functions, Prev: Other libpq Functions, Up: XEmacs PostgreSQL libpq API + +Unimplemented libpq Functions +----------------------------- + + - Unimplemented Function: PGconn *PQsetdbLogin (char *pghost, char + *pgport, char *pgoptions, char *pgtty, char *dbName, char + *login, char *pwd) + Synchronous database connection. PGHOST is the hostname of the + PostgreSQL backend to connect to. PGPORT is the TCP port number + to use. PGOPTIONS specifies other backend options. PGTTY + specifies the debugging tty to use. DBNAME specifies the database + name to use. LOGIN specifies the database user name. PWD + specifies the database user's password. + + This routine is deprecated as of libpq-7.0, and its functionality + can be replaced by external Lisp code if needed. + + - Unimplemented Function: PGconn *PQsetdb (char *pghost, char *pgport, + char *pgoptions, char *pgtty, char *dbName) + Synchronous database connection. PGHOST is the hostname of the + PostgreSQL backend to connect to. PGPORT is the TCP port number + to use. PGOPTIONS specifies other backend options. PGTTY + specifies the debugging tty to use. DBNAME specifies the database + name to use. + + This routine was deprecated in libpq-6.5. + + - Unimplemented Function: int PQsocket (PGconn *conn) + Return socket file descriptor to a backend database process. CONN + database connection object. + + - Unimplemented Function: void PQprint (FILE *fout, PGresult *res, + PGprintOpt *ps) + Print out the results of a query to a designated C stream. FOUT C + stream to print to RES the query result object to print PS the + print options structure. + + This routine is deprecated as of libpq-7.0 and cannot be sensibly + exported to XEmacs Lisp. + + - Unimplemented Function: void PQdisplayTuples (PGresult *res, FILE + *fp, int fillAlign, char *fieldSep, int printHeader, int + quiet) + RES query result object to print FP C stream to print to FILLALIGN + pad the fields with spaces FIELDSEP field separator PRINTHEADER + display headers? QUIET + + This routine was deprecated in libpq-6.5. + + - Unimplemented Function: void PQprintTuples (PGresult *res, FILE + *fout, int printAttName, int terseOutput, int width) + RES query result object to print FOUT C stream to print to + PRINTATTNAME print attribute names TERSEOUTPUT delimiter bars + WIDTH width of column, if 0, use variable width + + This routine was deprecated in libpq-6.5. + + - Unimplemented Function: int PQmblen (char *s, int encoding) + Determine length of a multibyte encoded char at `*s'. S encoded + string ENCODING type of encoding + + Compatibility note: This function was introduced in libpq-7.0. + + - Unimplemented Function: void PQtrace (PGconn *conn, FILE *debug_port) + Enable tracing on `debug_port'. CONN database connection object. + DEBUG_PORT C output stream to use. + + - Unimplemented Function: void PQuntrace (PGconn *conn) + Disable tracing. CONN database connection object. + + - Unimplemented Function: char *PQoidStatus (PGconn *conn) + Return the object id as a string of the last tuple inserted. CONN + database connection object. + + Compatibility note: This function is deprecated in libpq-7.0, + however it is used internally by the XEmacs binding code when + linked against versions prior to 7.0. + + - Unimplemented Function: PGresult *PQfn (PGconn *conn, int fnid, int + *result_buf, int *result_len, int result_is_int, PQArgBlock + *args, int nargs) + "Fast path" interface -- not really recommended for application use + CONN A database connection object. FNID RESULT_BUF RESULT_LEN + RESULT_IS_INT ARGS NARGS + + The following set of very low level large object functions aren't +appropriate to be exported to Lisp. + + - Unimplemented Function: int pq-lo-open (PGconn *conn, int lobjid, + int mode) + CONN a database connection object. LOBJID a large object ID. + MODE opening modes. + + - Unimplemented Function: int pq-lo-close (PGconn *conn, int fd) + CONN a database connection object. FD a large object file + descriptor + + - Unimplemented Function: int pq-lo-read (PGconn *conn, int fd, char + *buf, int len) + CONN a database connection object. FD a large object file + descriptor. BUF buffer to read into. LEN size of buffer. + + - Unimplemented Function: int pq-lo-write (PGconn *conn, int fd, char + *buf, size_t len) + CONN a database connection object. FD a large object file + descriptor. BUF buffer to write from. LEN size of buffer. + + - Unimplemented Function: int pq-lo-lseek (PGconn *conn, int fd, int + offset, int whence) + CONN a database connection object. FD a large object file + descriptor. OFFSET WHENCE -`terminal-mode-break-hook' + - Unimplemented Function: int pq-lo-creat (PGconn *conn, int mode) + CONN a database connection object. MODE opening modes. + + - Unimplemented Function: int pq-lo-tell (PGconn *conn, int fd) + CONN a database connection object. FD a large object file + descriptor. + + - Unimplemented Function: int pq-lo-unlink (PGconn *conn, int lobjid) + CONN a database connection object. LBOJID a large object ID. -`TeX-mode-hook' + +File: lispref.info, Node: XEmacs PostgreSQL libpq Examples, Prev: XEmacs PostgreSQL libpq API, Up: PostgreSQL Support + +XEmacs PostgreSQL libpq Examples +================================ + + This is an example of one method of establishing an asynchronous +connection. + + (defun database-poller (P) + (message "%S before poll" (pq-pgconn P 'pq::status)) + (pq-connect-poll P) + (message "%S after poll" (pq-pgconn P 'pq::status)) + (if (eq (pq-pgconn P 'pq::status) 'pg::connection-ok) + (message "Done!") + (add-timeout .1 'database-poller P))) + => database-poller + (progn + (setq P (pq-connect-start "")) + (add-timeout .1 'database-poller P)) + => pg::connection-started before poll + => pg::connection-made after poll + => pg::connection-made before poll + => pg::connection-awaiting-response after poll + => pg::connection-awaiting-response before poll + => pg::connection-auth-ok after poll + => pg::connection-auth-ok before poll + => pg::connection-setenv after poll + => pg::connection-setenv before poll + => pg::connection-ok after poll + => Done! + P + => # + + Here is an example of one method of doing an asynchronous reset. + + (defun database-poller (P) + (let (PS) + (message "%S before poll" (pq-pgconn P 'pq::status)) + (setq PS (pq-reset-poll P)) + (message "%S after poll [%S]" (pq-pgconn P 'pq::status) PS) + (if (eq (pq-pgconn P 'pq::status) 'pg::connection-ok) + (message "Done!") + (add-timeout .1 'database-poller P)))) + => database-poller + (progn + (pq-reset-start P) + (add-timeout .1 'database-poller P)) + => pg::connection-started before poll + => pg::connection-made after poll [pgres::polling-writing] + => pg::connection-made before poll + => pg::connection-awaiting-response after poll [pgres::polling-reading] + => pg::connection-awaiting-response before poll + => pg::connection-setenv after poll [pgres::polling-reading] + => pg::connection-setenv before poll + => pg::connection-ok after poll [pgres::polling-ok] + => Done! + P + => # + + And finally, an asynchronous query. + + (defun database-poller (P) + (let (R) + (pq-consume-input P) + (if (pq-is-busy P) + (add-timeout .1 'database-poller P) + (setq R (pq-get-result P)) + (if R + (progn + (push R result-list) + (add-timeout .1 'database-poller P)))))) + => database-poller + (when (pq-send-query P "SELECT * FROM xemacs_test;") + (setq result-list nil) + (add-timeout .1 'database-poller P)) + => 885 + ;; wait a moment + result-list + => (#) + + Here is an example showing how multiple SQL statements in a single +query can have all their results collected. + ;; Using the same `database-poller' function from the previous example + (when (pq-send-query P "SELECT * FROM xemacs_test; + SELECT * FROM pg_database; + SELECT * FROM pg_user;") + (setq result-list nil) + (add-timeout .1 'database-poller P)) + => 1782 + ;; wait a moment + result-list + => (# # #) + + Here is an example which illustrates collecting all data from a +query, including the field names. + + (defun pg-util-query-results (results) + "Retrieve results of last SQL query into a list structure." + (let ((i (1- (pq-ntuples R))) + j l1 l2) + (while (>= i 0) + (setq j (1- (pq-nfields R))) + (setq l2 nil) + (while (>= j 0) + (push (pq-get-value R i j) l2) + (decf j)) + (push l2 l1) + (decf i)) + (setq j (1- (pq-nfields R))) + (setq l2 nil) + (while (>= j 0) + (push (pq-fname R j) l2) + (decf j)) + (push l2 l1) + l1)) + => pg-util-query-results + (setq R (pq-exec P "SELECT * FROM xemacs_test ORDER BY field2 DESC;")) + => # + (pg-util-query-results R) + => (("f1" "field2") ("a" "97") ("b" "97") ("stuff" "42") ("a string" "12") ("foo" "10") ("string" "2") ("text" "1")) + + Here is an example of a query that uses a database cursor. + + (let (data R) + (setq R (pq-exec P "BEGIN;")) + (setq R (pq-exec P "DECLARE k_cursor CURSOR FOR SELECT * FROM xemacs_test ORDER BY f1 DESC;")) + + (setq R (pq-exec P "FETCH k_cursor;")) + (while (eq (pq-ntuples R) 1) + (push (list (pq-get-value R 0 0) (pq-get-value R 0 1)) data) + (setq R (pq-exec P "FETCH k_cursor;"))) + (setq R (pq-exec P "END;")) + data) + => (("a" "97") ("a string" "12") ("b" "97") ("foo" "10") ("string" "2") ("stuff" "42") ("text" "1")) + + Here's another example of cursors, this time with a Lisp macro to +implement a mapping function over a table. + + (defmacro map-db (P table condition callout) + `(let (R) + (pq-exec ,P "BEGIN;") + (pq-exec ,P (concat "DECLARE k_cursor CURSOR FOR SELECT * FROM " + ,table + " " + ,condition + " ORDER BY f1 DESC;")) + (setq R (pq-exec P "FETCH k_cursor;")) + (while (eq (pq-ntuples R) 1) + (,callout (pq-get-value R 0 0) (pq-get-value R 0 1)) + (setq R (pq-exec P "FETCH k_cursor;"))) + (pq-exec P "END;"))) + => map-db + (defun callback (arg1 arg2) + (message "arg1 = %s, arg2 = %s" arg1 arg2)) + => callback + (map-db P "xemacs_test" "WHERE field2 > 10" callback) + => arg1 = stuff, arg2 = 42 + => arg1 = b, arg2 = 97 + => arg1 = a string, arg2 = 12 + => arg1 = a, arg2 = 97 + => # -`tex-mode-hook' + +File: lispref.info, Node: Internationalization, Next: MULE, Prev: PostgreSQL Support, Up: Top -`text-mode-hook' +Internationalization +******************** -`today-visible-calendar-hook' +* Menu: -`today-invisible-calendar-hook' +* I18N Levels 1 and 2:: Support for different time, date, and currency formats. +* I18N Level 3:: Support for localized messages. +* I18N Level 4:: Support for Asian languages. -`tooltalk-message-handler-hook' + +File: lispref.info, Node: I18N Levels 1 and 2, Next: I18N Level 3, Up: Internationalization -`tooltalk-pattern-handler-hook' +I18N Levels 1 and 2 +=================== -`tooltalk-unprocessed-message-hook' + XEmacs is now compliant with I18N levels 1 and 2. Specifically, +this means that it is 8-bit clean and correctly handles time and date +functions. XEmacs will correctly display the entire ISO-Latin 1 +character set. -`unmap-frame-hook' + The compose key may now be used to create any character in the +ISO-Latin 1 character set not directly available via the keyboard.. In +order for the compose key to work it is necessary to load the file +`x-compose.el'. At any time while composing a character, `C-h' will +display all valid completions and the character which would be produced. -`vc-checkin-hook' + +File: lispref.info, Node: I18N Level 3, Next: I18N Level 4, Prev: I18N Levels 1 and 2, Up: Internationalization -`vc-checkout-writable-buffer-hook' +I18N Level 3 +============ -`vc-log-after-operation-hook' +* Menu: -`vc-make-buffer-writable-hook' +* Level 3 Basics:: +* Level 3 Primitives:: +* Dynamic Messaging:: +* Domain Specification:: +* Documentation String Extraction:: -`view-hook' + +File: lispref.info, Node: Level 3 Basics, Next: Level 3 Primitives, Up: I18N Level 3 -`vm-arrived-message-hook' +Level 3 Basics +-------------- -`vm-arrived-messages-hook' + XEmacs now provides alpha-level functionality for I18N Level 3. +This means that everything necessary for full messaging is available, +but not every file has been converted. -`vm-chop-full-name-function' + The two message files which have been created are `src/emacs.po' and +`lisp/packages/mh-e.po'. Both files need to be converted using +`msgfmt', and the resulting `.mo' files placed in some locale's +`LC_MESSAGES' directory. The test "translations" in these files are +the original messages prefixed by `TRNSLT_'. -`vm-display-buffer-hook' + The domain for a variable is stored on the variable's property list +under the property name VARIABLE-DOMAIN. The function +`documentation-property' uses this information when translating a +variable's documentation. -`vm-edit-message-hook' + +File: lispref.info, Node: Level 3 Primitives, Next: Dynamic Messaging, Prev: Level 3 Basics, Up: I18N Level 3 -`vm-forward-message-hook' +Level 3 Primitives +------------------ -`vm-iconify-frame-hook' + - Function: gettext string + This function looks up STRING in the default message domain and + returns its translation. If `I18N3' was not enabled when XEmacs + was compiled, it just returns STRING. -`vm-inhibit-write-file-hook' + - Function: dgettext domain string + This function looks up STRING in the specified message domain and + returns its translation. If `I18N3' was not enabled when XEmacs + was compiled, it just returns STRING. -`vm-key-functions' + - Function: bind-text-domain domain pathname + This function associates a pathname with a message domain. Here's + how the path to message file is constructed under SunOS 5.x: -`vm-mail-hook' + `{pathname}/{LANG}/LC_MESSAGES/{domain}.mo' -`vm-mail-mode-hook' + If `I18N3' was not enabled when XEmacs was compiled, this function + does nothing. -`vm-menu-setup-hook' + - Special Form: domain string + This function specifies the text domain used for translating + documentation strings and interactive prompts of a function. For + example, write: -`vm-mode-hook' + (defun foo (arg) "Doc string" (domain "emacs-foo") ...) -`vm-quit-hook' + to specify `emacs-foo' as the text domain of the function `foo'. + The "call" to `domain' is actually a declaration rather than a + function; when actually called, `domain' just returns `nil'. -`vm-rename-current-buffer-function' + - Function: domain-of function + This function returns the text domain of FUNCTION; it returns + `nil' if it is the default domain. If `I18N3' was not enabled + when XEmacs was compiled, it always returns `nil'. -`vm-reply-hook' + +File: lispref.info, Node: Dynamic Messaging, Next: Domain Specification, Prev: Level 3 Primitives, Up: I18N Level 3 -`vm-resend-bounced-message-hook' +Dynamic Messaging +----------------- -`vm-resend-message-hook' + The `format' function has been extended to permit you to change the +order of parameter insertion. For example, the conversion format +`%1$s' inserts parameter one as a string, while `%2$s' inserts +parameter two. This is useful when creating translations which require +you to change the word order. -`vm-retrieved-spooled-mail-hook' + +File: lispref.info, Node: Domain Specification, Next: Documentation String Extraction, Prev: Dynamic Messaging, Up: I18N Level 3 -`vm-select-message-hook' +Domain Specification +-------------------- -`vm-select-new-message-hook' + The default message domain of XEmacs is `emacs'. For add-on +packages, it is best to use a different domain. For example, let us +say we want to convert the "gorilla" package to use the domain +`emacs-gorilla'. To translate the message "What gorilla?", use +`dgettext' as follows: -`vm-select-unread-message-hook' + (dgettext "emacs-gorilla" "What gorilla?") -`vm-send-digest-hook' + A function (or macro) which has a documentation string or an +interactive prompt needs to be associated with the domain in order for +the documentation or prompt to be translated. This is done with the +`domain' special form as follows: -`vm-summary-mode-hook' + (defun scratch (location) + "Scratch the specified location." + (domain "emacs-gorilla") + (interactive "sScratch: ") + ... ) -`vm-summary-pointer-update-hook' + It is most efficient to specify the domain in the first line of the +function body, before the `interactive' form. -`vm-summary-redo-hook' + For variables and constants which have documentation strings, +specify the domain after the documentation. -`vm-summary-update-hook' + - Special Form: defvar symbol [value [doc-string [domain]]] + Example: + (defvar weight 250 "Weight of gorilla, in pounds." "emacs-gorilla") -`vm-undisplay-buffer-hook' + - Special Form: defconst symbol [value [doc-string [domain]]] + Example: + (defconst limbs 4 "Number of limbs" "emacs-gorilla") -`vm-visit-folder-hook' + - Function: autoload function filename &optional docstring interactive + type + This function defines FUNCTION to autoload from FILENAME Example: + (autoload 'explore "jungle" "Explore the jungle." nil nil "emacs-gorilla") -`window-setup-hook' + +File: lispref.info, Node: Documentation String Extraction, Prev: Domain Specification, Up: I18N Level 3 -`write-contents-hooks' +Documentation String Extraction +------------------------------- -`write-file-data-hooks' + The utility `etc/make-po' scans the file `DOC' to extract +documentation strings and creates a message file `doc.po'. This file +may then be inserted within `emacs.po'. -`write-file-hooks' + Currently, `make-po' is hard-coded to read from `DOC' and write to +`doc.po'. In order to extract documentation strings from an add-on +package, first run `make-docfile' on the package to produce the `DOC' +file. Then run `make-po -p' with the `-p' argument to indicate that we +are extracting documentation for an add-on package. -`write-region-annotate-functions' + (The `-p' argument is a kludge to make up for a subtle difference +between pre-loaded documentation and add-on documentation: For add-on +packages, the final carriage returns in the strings produced by +`make-docfile' must be ignored.) -`x-lost-selection-hooks' + +File: lispref.info, Node: I18N Level 4, Prev: I18N Level 3, Up: Internationalization -`x-sent-selection-hooks' +I18N Level 4 +============ -`zmacs-activate-region-hook' + The Asian-language support in XEmacs is called "MULE". *Note MULE::. -`zmacs-deactivate-region-hook' + +File: lispref.info, Node: MULE, Next: Tips, Prev: Internationalization, Up: Top + +MULE +**** + + "MULE" is the name originally given to the version of GNU Emacs +extended for multi-lingual (and in particular Asian-language) support. +"MULE" is short for "MUlti-Lingual Emacs". It is an extension and +complete rewrite of Nemacs ("Nihon Emacs" where "Nihon" is the Japanese +word for "Japan"), which only provided support for Japanese. XEmacs +refers to its multi-lingual support as "MULE support" since it is based +on "MULE". + +* Menu: + +* Internationalization Terminology:: + Definition of various internationalization terms. +* Charsets:: Sets of related characters. +* MULE Characters:: Working with characters in XEmacs/MULE. +* Composite Characters:: Making new characters by overstriking other ones. +* Coding Systems:: Ways of representing a string of chars using integers. +* CCL:: A special language for writing fast converters. +* Category Tables:: Subdividing charsets into groups. -`zmacs-update-region-hook'