X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-42;h=615cb1f48f62b78f8f8166fbe2c19a51393f027d;hb=f25aa1d46f1ded748f0ea4bcf875441a538ec14a;hp=aebbf29bf4e8abfec56b07840b70a1784ef2a08b;hpb=7d6edaefa00e7b7e102354283824a4f6a721b71a;p=chise%2Fxemacs-chise.git- diff --git a/info/lispref.info-42 b/info/lispref.info-42 index aebbf29..615cb1f 100644 --- a/info/lispref.info-42 +++ b/info/lispref.info-42 @@ -1,4 +1,4 @@ -This is ../info/lispref.info, produced by makeinfo version 4.0 from +This is ../info/lispref.info, produced by makeinfo version 4.0b from lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor @@ -50,1012 +50,1083 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -File: lispref.info, Node: Big5 and Shift-JIS Functions, Prev: Detection of Textual Encoding, Up: Coding Systems +File: lispref.info, Node: Grabs, Prev: Server Data, Up: X Server + +Restricting Access to the Server by Other Apps +---------------------------------------------- + + - Function: x-grab-keyboard &optional device + This function grabs the keyboard on the given device (defaulting + to the selected one). So long as the keyboard is grabbed, all + keyboard events will be delivered to XEmacs--it is not possible + for other X clients to eavesdrop on them. Ungrab the keyboard + with `x-ungrab-keyboard' (use an `unwind-protect'). Returns `t' + if the grab was successful; `nil' otherwise. + + - Function: x-ungrab-keyboard &optional device + This function releases a keyboard grab made with `x-grab-keyboard'. + + - Function: x-grab-pointer &optional device cursor ignore-keyboard + This function grabs the pointer and restricts it to its current + window. If optional DEVICE argument is `nil', the selected device + will be used. If optional CURSOR argument is non-`nil', change + the pointer shape to that until `x-ungrab-pointer' is called (it + should be an object returned by the `make-cursor' function). If + the second optional argument IGNORE-KEYBOARD is non-`nil', ignore + all keyboard events during the grab. Returns `t' if the grab is + successful, `nil' otherwise. + + - Function: x-ungrab-pointer &optional device + This function releases a pointer grab made with `x-grab-pointer'. + If optional first arg DEVICE is `nil' the selected device is used. + If it is `t' the pointer will be released on all X devices. -Big5 and Shift-JIS Functions ----------------------------- + +File: lispref.info, Node: X Miscellaneous, Prev: X Server, Up: X-Windows + +Miscellaneous X Functions and Variables +======================================= + + - Variable: x-bitmap-file-path + This variable holds a list of the directories in which X bitmap + files may be found. If `nil', this is initialized from the + `"*bitmapFilePath"' resource. This is used by the + `make-image-instance' function (however, note that if the + environment variable `XBMLANGPATH' is set, it is consulted first). + + - Variable: x-library-search-path + This variable holds the search path used by `read-color' to find + `rgb.txt'. + + - Function: x-valid-keysym-name-p keysym + This function returns true if KEYSYM names a keysym that the X + library knows about. Valid keysyms are listed in the files + `/usr/include/X11/keysymdef.h' and in `/usr/lib/X11/XKeysymDB', or + whatever the equivalents are on your system. + + - Function: x-window-id &optional frame + This function returns the ID of the X11 window. This gives us a + chance to manipulate the Emacs window from within a different + program. Since the ID is an unsigned long, we return it as a + string. + + - Variable: x-allow-sendevents + If non-`nil', synthetic events are allowed. `nil' means they are + ignored. Beware: allowing XEmacs to process SendEvents opens a + big security hole. + + - Function: x-debug-mode arg &optional device + With a true arg, make the connection to the X server synchronous. + With false, make it asynchronous. Synchronous connections are + much slower, but are useful for debugging. (If you get X errors, + make the connection synchronous, and use a debugger to set a + breakpoint on `x_error_handler'. Your backtrace of the C stack + will now be useful. In asynchronous mode, the stack above + `x_error_handler' isn't helpful because of buffering.) If DEVICE + is not specified, the selected device is assumed. + + Calling this function is the same as calling the C function + `XSynchronize', or starting the program with the `-sync' command + line argument. + + - Variable: x-debug-events + If non-zero, debug information about events that XEmacs sees is + displayed. Information is displayed on stderr. Currently defined + values are: + + * 1 == non-verbose output + + * 2 == verbose output + + +File: lispref.info, Node: ToolTalk Support, Next: LDAP Support, Prev: X-Windows, Up: Top + +ToolTalk Support +**************** + +* Menu: + +* XEmacs ToolTalk API Summary:: +* Sending Messages:: +* Receiving Messages:: - These are special functions for working with the non-standard -Shift-JIS and Big5 encodings. + +File: lispref.info, Node: XEmacs ToolTalk API Summary, Next: Sending Messages, Up: ToolTalk Support + +XEmacs ToolTalk API Summary +=========================== + + The XEmacs Lisp interface to ToolTalk is similar, at least in spirit, +to the standard C ToolTalk API. Only the message and pattern parts of +the API are supported at present; more of the API could be added if +needed. The Lisp interface departs from the C API in a few ways: - - Function: decode-shift-jis-char code - This function decodes a JISX0208 character of Shift-JIS - coding-system. CODE is the character code in Shift-JIS as a cons - of type bytes. The corresponding character is returned. + * ToolTalk is initialized automatically at XEmacs startup-time. + Messages can only be sent other ToolTalk applications connected to + the same X11 server that XEmacs is running on. - - Function: encode-shift-jis-char ch - This function encodes a JISX0208 character CH to SHIFT-JIS - coding-system. The corresponding character code in SHIFT-JIS is - returned as a cons of two bytes. + * There are fewer entry points; polymorphic functions with keyword + arguments are used instead. - - Function: decode-big5-char code - This function decodes a Big5 character CODE of BIG5 coding-system. - CODE is the character code in BIG5. The corresponding character - is returned. + * The callback interface is simpler and marginally less functional. + A single callback may be associated with a message or a pattern; + the callback is specified with a Lisp symbol (the symbol should + have a function binding). - - Function: encode-big5-char ch - This function encodes the Big5 character CHAR to BIG5 - coding-system. The corresponding character code in Big5 is - returned. + * The session attribute for messages and patterns is always + initialized to the default session. + + * Anywhere a ToolTalk enum constant, e.g. `TT_SESSION', is valid, one + can substitute the corresponding symbol, e.g. `'TT_SESSION'. This + simplifies building lists that represent messages and patterns.  -File: lispref.info, Node: CCL, Next: Category Tables, Prev: Coding Systems, Up: MULE - -CCL -=== - - CCL (Code Conversion Language) is a simple structured programming -language designed for character coding conversions. A CCL program is -compiled to CCL code (represented by a vector of integers) and executed -by the CCL interpreter embedded in Emacs. The CCL interpreter -implements a virtual machine with 8 registers called `r0', ..., `r7', a -number of control structures, and some I/O operators. Take care when -using registers `r0' (used in implicit "set" statements) and especially -`r7' (used internally by several statements and operations, especially -for multiple return values and I/O operations). - - CCL is used for code conversion during process I/O and file I/O for -non-ISO2022 coding systems. (It is the only way for a user to specify a -code conversion function.) It is also used for calculating the code -point of an X11 font from a character code. However, since CCL is -designed as a powerful programming language, it can be used for more -generic calculation where efficiency is demanded. A combination of -three or more arithmetic operations can be calculated faster by CCL than -by Emacs Lisp. - - *Warning:* The code in `src/mule-ccl.c' and -`$packages/lisp/mule-base/mule-ccl.el' is the definitive description of -CCL's semantics. The previous version of this section contained -several typos and obsolete names left from earlier versions of MULE, -and many may remain. (I am not an experienced CCL programmer; the few -who know CCL well find writing English painful.) - - A CCL program transforms an input data stream into an output data -stream. The input stream, held in a buffer of constant bytes, is left -unchanged. The buffer may be filled by an external input operation, -taken from an Emacs buffer, or taken from a Lisp string. The output -buffer is a dynamic array of bytes, which can be written by an external -output operation, inserted into an Emacs buffer, or returned as a Lisp -string. - - A CCL program is a (Lisp) list containing two or three members. The -first member is the "buffer magnification", which indicates the -required minimum size of the output buffer as a multiple of the input -buffer. It is followed by the "main block" which executes while there -is input remaining, and an optional "EOF block" which is executed when -the input is exhausted. Both the main block and the EOF block are CCL -blocks. - - A "CCL block" is either a CCL statement or list of CCL statements. -A "CCL statement" is either a "set statement" (either an integer or an -"assignment", which is a list of a register to receive the assignment, -an assignment operator, and an expression) or a "control statement" (a -list starting with a keyword, whose allowable syntax depends on the -keyword). +File: lispref.info, Node: Sending Messages, Next: Receiving Messages, Prev: XEmacs ToolTalk API Summary, Up: ToolTalk Support + +Sending Messages +================ * Menu: -* CCL Syntax:: CCL program syntax in BNF notation. -* CCL Statements:: Semantics of CCL statements. -* CCL Expressions:: Operators and expressions in CCL. -* Calling CCL:: Running CCL programs. -* CCL Examples:: The encoding functions for Big5 and KOI-8. +* Example of Sending Messages:: +* Elisp Interface for Sending Messages::  -File: lispref.info, Node: CCL Syntax, Next: CCL Statements, Prev: CCL, Up: CCL - -CCL Syntax ----------- - - The full syntax of a CCL program in BNF notation: - -CCL_PROGRAM := - (BUFFER_MAGNIFICATION - CCL_MAIN_BLOCK - [ CCL_EOF_BLOCK ]) - -BUFFER_MAGNIFICATION := integer -CCL_MAIN_BLOCK := CCL_BLOCK -CCL_EOF_BLOCK := CCL_BLOCK - -CCL_BLOCK := - STATEMENT | (STATEMENT [STATEMENT ...]) -STATEMENT := - SET | IF | BRANCH | LOOP | REPEAT | BREAK | READ | WRITE - | CALL | END - -SET := - (REG = EXPRESSION) - | (REG ASSIGNMENT_OPERATOR EXPRESSION) - | integer - -EXPRESSION := ARG | (EXPRESSION OPERATOR ARG) - -IF := (if EXPRESSION CCL_BLOCK [CCL_BLOCK]) -BRANCH := (branch EXPRESSION CCL_BLOCK [CCL_BLOCK ...]) -LOOP := (loop STATEMENT [STATEMENT ...]) -BREAK := (break) -REPEAT := - (repeat) - | (write-repeat [REG | integer | string]) - | (write-read-repeat REG [integer | ARRAY]) -READ := - (read REG ...) - | (read-if (REG OPERATOR ARG) CCL_BLOCK CCL_BLOCK) - | (read-branch REG CCL_BLOCK [CCL_BLOCK ...]) -WRITE := - (write REG ...) - | (write EXPRESSION) - | (write integer) | (write string) | (write REG ARRAY) - | string -CALL := (call ccl-program-name) -END := (end) - -REG := r0 | r1 | r2 | r3 | r4 | r5 | r6 | r7 -ARG := REG | integer -OPERATOR := - + | - | * | / | % | & | '|' | ^ | << | >> | <8 | >8 | // - | < | > | == | <= | >= | != | de-sjis | en-sjis -ASSIGNMENT_OPERATOR := - += | -= | *= | /= | %= | &= | '|=' | ^= | <<= | >>= -ARRAY := '[' integer ... ']' +File: lispref.info, Node: Example of Sending Messages, Next: Elisp Interface for Sending Messages, Up: Sending Messages + +Example of Sending Messages +--------------------------- + + Here's a simple example that sends a query to another application +and then displays its reply. Both the query and the reply are stored +in the first argument of the message. + + (defun tooltalk-random-query-handler (msg) + (let ((state (get-tooltalk-message-attribute msg 'state))) + (cond + ((eq state 'TT_HANDLED) + (message (get-tooltalk-message-attribute msg arg_val 0))) + ((memq state '(TT_FAILED TT_REJECTED)) + (message "Random query turns up nothing"))))) + + (defvar random-query-message + '( class TT_REQUEST + scope TT_SESSION + address TT_PROCEDURE + op "random-query" + args '((TT_INOUT "?" "string")) + callback tooltalk-random-query-handler)) + + (let ((m (make-tooltalk-message random-query-message))) + (send-tooltalk-message m))  -File: lispref.info, Node: CCL Statements, Next: CCL Expressions, Prev: CCL Syntax, Up: CCL +File: lispref.info, Node: Elisp Interface for Sending Messages, Prev: Example of Sending Messages, Up: Sending Messages + +Elisp Interface for Sending Messages +------------------------------------ + + - Function: make-tooltalk-message attributes + Create a ToolTalk message and initialize its attributes. The + value of ATTRIBUTES must be a list of alternating keyword/values, + where keywords are symbols that name valid message attributes. + For example: + + (make-tooltalk-message + '(class TT_NOTICE + scope TT_SESSION + address TT_PROCEDURE + op "do-something" + args ("arg1" 12345 (TT_INOUT "arg3" "string")))) + + Values must always be strings, integers, or symbols that represent + ToolTalk constants. Attribute names are the same as those + supported by `set-tooltalk-message-attribute', plus `args'. + + The value of `args' should be a list of message arguments where + each message argument has the following form: + + `(mode [value [type]])' or just `value' + + Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is + a string. If TYPE isn't specified then `int' is used if VALUE is + a number; otherwise `string' is used. If TYPE is `string' then + VALUE is converted to a string (if it isn't a string already) with + `prin1-to-string'. If only a value is specified then MODE + defaults to `TT_IN'. If MODE is `TT_OUT' then VALUE and TYPE + don't need to be specified. You can find out more about the + semantics and uses of ToolTalk message arguments in chapter 4 of + the `ToolTalk Programmer's Guide'. + + + - Function: send-tooltalk-message msg + Send the message on its way. Once the message has been sent it's + almost always a good idea to get rid of it with + `destroy-tooltalk-message'. + + + - Function: return-tooltalk-message msg &optional mode + Send a reply to this message. The second argument can be `reply', + `reject' or `fail'; the default is `reply'. Before sending a + reply, all message arguments whose mode is `TT_INOUT' or `TT_OUT' + should have been filled in--see `set-tooltalk-message-attribute'. + + + - Function: get-tooltalk-message-attribute msg attribute &optional argn + Returns the indicated ToolTalk message attribute. Attributes are + identified by symbols with the same name (underscores and all) as + the suffix of the ToolTalk `tt_message_' function that + extracts the value. String attribute values are copied and + enumerated type values (except disposition) are converted to + symbols; e.g. `TT_HANDLER' is `'TT_HANDLER', `uid' and `gid' are + represented by fixnums (small integers), `opnum' is converted to a + string, and `disposition' is converted to a fixnum. We convert + `opnum' (a C int) to a string (e.g. `123' => `"123"') because + there's no guarantee that opnums will fit within the range of + XEmacs Lisp integers. + + [TBD] Use the `plist' attribute instead of C API `user' attribute + for user-defined message data. To retrieve the value of a message + property, specify the indicator for ARGN. For example, to get the + value of a property called `rflag', use + + (get-tooltalk-message-attribute msg 'plist 'rflag) + + To get the value of a message argument use one of the `arg_val' + (strings), `arg_ival' (integers), or `arg_bval' (strings with + embedded nulls), attributes. For example, to get the integer + value of the third argument: + + (get-tooltalk-message-attribute msg 'arg_ival 2) + + As you can see, argument numbers are zero-based. The type of each + arguments can be retrieved with the `arg_type' attribute; however + ToolTalk doesn't define any semantics for the string value of + `arg_type'. Conventionally `string' is used for strings and `int' + for 32 bit integers. Note that XEmacs Lisp stores the lengths of + strings explicitly (unlike C) so treating the value returned by + `arg_bval' like a string is fine. + + + - Function: set-tooltalk-message-attribute value msg attribute + &optional argn + Initialize one ToolTalk message attribute. + + Attribute names and values are the same as for + `get-tooltalk-message-attribute'. A property list is provided for + user data (instead of the `user' message attribute); see + `get-tooltalk-message-attribute'. + + Callbacks are handled slightly differently than in the C ToolTalk + API. The value of CALLBACK should be the name of a function of one + argument. It will be called each time the state of the message + changes. This is usually used to notice when the message's state + has changed to `TT_HANDLED' (or `TT_FAILED'), so that reply + argument values can be used. + + If one of the argument attributes is specified as `arg_val', + `arg_ival', or `arg_bval', then ARGN must be the number of an + already created argument. Arguments can be added to a message + with `add-tooltalk-message-arg'. + + + - Function: add-tooltalk-message-arg msg mode type &optional value + Append one new argument to the message. MODE must be one of + `TT_IN', `TT_INOUT', or `TT_OUT', TYPE must be a string, and VALUE + can be a string or an integer. ToolTalk doesn't define any + semantics for TYPE, so only the participants in the protocol + you're using need to agree what types mean (if anything). + Conventionally `string' is used for strings and `int' for 32 bit + integers. Arguments can initialized by providing a value or with + `set-tooltalk-message-attribute'; the latter is necessary if you + want to initialize the argument with a string that can contain + embedded nulls (use `arg_bval'). + + + - Function: create-tooltalk-message &optional no-callback + Create a new ToolTalk message. The message's session attribute is + initialized to the default session. Other attributes can be + initialized with `set-tooltalk-message-attribute'. + `make-tooltalk-message' is the preferred way to create and + initialize a message. + + Optional arg NO-CALLBACK says don't add a C-level callback at all. + Normally don't do that; just don't specify the Lisp callback when + calling `make-tooltalk-message'. + + + - Function: destroy-tooltalk-message msg + Apply `tt_message_destroy' to the message. It's not necessary to + destroy messages after they've been processed by a message or + pattern callback, the Lisp/ToolTalk callback machinery does this + for you. -CCL Statements --------------- + +File: lispref.info, Node: Receiving Messages, Prev: Sending Messages, Up: ToolTalk Support - The Emacs Code Conversion Language provides the following statement -types: "set", "if", "branch", "loop", "repeat", "break", "read", -"write", "call", and "end". +Receiving Messages +================== -Set statement: -============== +* Menu: - The "set" statement has three variants with the syntaxes `(REG = -EXPRESSION)', `(REG ASSIGNMENT_OPERATOR EXPRESSION)', and `INTEGER'. -The assignment operator variation of the "set" statement works the same -way as the corresponding C expression statement does. The assignment -operators are `+=', `-=', `*=', `/=', `%=', `&=', `|=', `^=', `<<=', -and `>>=', and they have the same meanings as in C. A "naked integer" -INTEGER is equivalent to a SET statement of the form `(r0 = INTEGER)'. +* Example of Receiving Messages:: +* Elisp Interface for Receiving Messages:: -I/O statements: -=============== + +File: lispref.info, Node: Example of Receiving Messages, Next: Elisp Interface for Receiving Messages, Up: Receiving Messages - The "read" statement takes one or more registers as arguments. It -reads one byte (a C char) from the input into each register in turn. - - The "write" takes several forms. In the form `(write REG ...)' it -takes one or more registers as arguments and writes each in turn to the -output. The integer in a register (interpreted as an Emchar) is -encoded to multibyte form (ie, Bufbytes) and written to the current -output buffer. If it is less than 256, it is written as is. The forms -`(write EXPRESSION)' and `(write INTEGER)' are treated analogously. -The form `(write STRING)' writes the constant string to the output. A -"naked string" `STRING' is equivalent to the statement `(write -STRING)'. The form `(write REG ARRAY)' writes the REGth element of the -ARRAY to the output. - -Conditional statements: -======================= - - The "if" statement takes an EXPRESSION, a CCL BLOCK, and an optional -SECOND CCL BLOCK as arguments. If the EXPRESSION evaluates to -non-zero, the first CCL BLOCK is executed. Otherwise, if there is a -SECOND CCL BLOCK, it is executed. - - The "read-if" variant of the "if" statement takes an EXPRESSION, a -CCL BLOCK, and an optional SECOND CCL BLOCK as arguments. The -EXPRESSION must have the form `(REG OPERATOR OPERAND)' (where OPERAND is -a register or an integer). The `read-if' statement first reads from -the input into the first register operand in the EXPRESSION, then -conditionally executes a CCL block just as the `if' statement does. - - The "branch" statement takes an EXPRESSION and one or more CCL -blocks as arguments. The CCL blocks are treated as a zero-indexed -array, and the `branch' statement uses the EXPRESSION as the index of -the CCL block to execute. Null CCL blocks may be used as no-ops, -continuing execution with the statement following the `branch' -statement in the containing CCL block. Out-of-range values for the -EXPRESSION are also treated as no-ops. - - The "read-branch" variant of the "branch" statement takes an -REGISTER, a CCL BLOCK, and an optional SECOND CCL BLOCK as arguments. -The `read-branch' statement first reads from the input into the -REGISTER, then conditionally executes a CCL block just as the `branch' -statement does. - -Loop control statements: -======================== +Example of Receiving Messages +----------------------------- - The "loop" statement creates a block with an implied jump from the -end of the block back to its head. The loop is exited on a `break' -statement, and continued without executing the tail by a `repeat' -statement. - - The "break" statement, written `(break)', terminates the current -loop and continues with the next statement in the current block. - - The "repeat" statement has three variants, `repeat', `write-repeat', -and `write-read-repeat'. Each continues the current loop from its -head, possibly after performing I/O. `repeat' takes no arguments and -does no I/O before jumping. `write-repeat' takes a single argument (a -register, an integer, or a string), writes it to the output, then jumps. -`write-read-repeat' takes one or two arguments. The first must be a -register. The second may be an integer or an array; if absent, it is -implicitly set to the first (register) argument. `write-read-repeat' -writes its second argument to the output, then reads from the input -into the register, and finally jumps. See the `write' and `read' -statements for the semantics of the I/O operations for each type of -argument. - -Other control statements: -========================= - - The "call" statement, written `(call CCL-PROGRAM-NAME)', executes a -CCL program as a subroutine. It does not return a value to the caller, -but can modify the register status. - - The "end" statement, written `(end)', terminates the CCL program -successfully, and returns to caller (which may be a CCL program). It -does not alter the status of the registers. + Here's a simple example of a handler for a message that tells XEmacs +to display a string in the mini-buffer area. The message operation is +called `emacs-display-string'. Its first (0th) argument is the string +to display. + + (defun tooltalk-display-string-handler (msg) + (message (get-tooltalk-message-attribute msg 'arg_val 0))) + + (defvar display-string-pattern + '(category TT_HANDLE + scope TT_SESSION + op "emacs-display-string" + callback tooltalk-display-string-handler)) + + (let ((p (make-tooltalk-pattern display-string-pattern))) + (register-tooltalk-pattern p))  -File: lispref.info, Node: CCL Expressions, Next: Calling CCL, Prev: CCL Statements, Up: CCL - -CCL Expressions ---------------- - - CCL, unlike Lisp, uses infix expressions. The simplest CCL -expressions consist of a single OPERAND, either a register (one of `r0', -..., `r0') or an integer. Complex expressions are lists of the form `( -EXPRESSION OPERATOR OPERAND )'. Unlike C, assignments are not -expressions. - - In the following table, X is the target resister for a "set". In -subexpressions, this is implicitly `r7'. This means that `>8', `//', -`de-sjis', and `en-sjis' cannot be used freely in subexpressions, since -they return parts of their values in `r7'. Y may be an expression, -register, or integer, while Z must be a register or an integer. - -Name Operator Code C-like Description -CCL_PLUS `+' 0x00 X = Y + Z -CCL_MINUS `-' 0x01 X = Y - Z -CCL_MUL `*' 0x02 X = Y * Z -CCL_DIV `/' 0x03 X = Y / Z -CCL_MOD `%' 0x04 X = Y % Z -CCL_AND `&' 0x05 X = Y & Z -CCL_OR `|' 0x06 X = Y | Z -CCL_XOR `^' 0x07 X = Y ^ Z -CCL_LSH `<<' 0x08 X = Y << Z -CCL_RSH `>>' 0x09 X = Y >> Z -CCL_LSH8 `<8' 0x0A X = (Y << 8) | Z -CCL_RSH8 `>8' 0x0B X = Y >> 8, r[7] = Y & 0xFF -CCL_DIVMOD `//' 0x0C X = Y / Z, r[7] = Y % Z -CCL_LS `<' 0x10 X = (X < Y) -CCL_GT `>' 0x11 X = (X > Y) -CCL_EQ `==' 0x12 X = (X == Y) -CCL_LE `<=' 0x13 X = (X <= Y) -CCL_GE `>=' 0x14 X = (X >= Y) -CCL_NE `!=' 0x15 X = (X != Y) -CCL_ENCODE_SJIS `en-sjis' 0x16 X = HIGHER_BYTE (SJIS (Y, Z)) - r[7] = LOWER_BYTE (SJIS (Y, Z) -CCL_DECODE_SJIS `de-sjis' 0x17 X = HIGHER_BYTE (DE-SJIS (Y, Z)) - r[7] = LOWER_BYTE (DE-SJIS (Y, Z)) - - The CCL operators are as in C, with the addition of CCL_LSH8, -CCL_RSH8, CCL_DIVMOD, CCL_ENCODE_SJIS, and CCL_DECODE_SJIS. The -CCL_ENCODE_SJIS and CCL_DECODE_SJIS treat their first and second bytes -as the high and low bytes of a two-byte character code. (SJIS stands -for Shift JIS, an encoding of Japanese characters used by Microsoft. -CCL_ENCODE_SJIS is a complicated transformation of the Japanese -standard JIS encoding to Shift JIS. CCL_DECODE_SJIS is its inverse.) -It is somewhat odd to represent the SJIS operations in infix form. +File: lispref.info, Node: Elisp Interface for Receiving Messages, Prev: Example of Receiving Messages, Up: Receiving Messages + +Elisp Interface for Receiving Messages +-------------------------------------- + + - Function: make-tooltalk-pattern attributes + Create a ToolTalk pattern and initialize its attributes. The + value of attributes must be a list of alternating keyword/values, + where keywords are symbols that name valid pattern attributes or + lists of valid attributes. For example: + + (make-tooltalk-pattern + '(category TT_OBSERVE + scope TT_SESSION + op ("operation1" "operation2") + args ("arg1" 12345 (TT_INOUT "arg3" "string")))) + + Attribute names are the same as those supported by + `add-tooltalk-pattern-attribute', plus `'args'. + + Values must always be strings, integers, or symbols that represent + ToolTalk constants or lists of same. When a list of values is + provided all of the list elements are added to the attribute. In + the example above, messages whose `op' attribute is `"operation1"' + or `"operation2"' would match the pattern. + + The value of ARGS should be a list of pattern arguments where each + pattern argument has the following form: + + `(mode [value [type]])' or just `value' + + Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is + a string. If TYPE isn't specified then `int' is used if VALUE is + a number; otherwise `string' is used. If TYPE is `string' then + VALUE is converted to a string (if it isn't a string already) with + `prin1-to-string'. If only a value is specified then MODE + defaults to `TT_IN'. If MODE is `TT_OUT' then VALUE and TYPE + don't need to be specified. You can find out more about the + semantics and uses of ToolTalk pattern arguments in chapter 3 of + the `ToolTalk Programmer's Guide'. + + + - Function: register-tooltalk-pattern pattern + XEmacs will begin receiving messages that match this pattern. + + - Function: unregister-tooltalk-pattern pattern + XEmacs will stop receiving messages that match this pattern. + + - Function: add-tooltalk-pattern-attribute value pattern indicator + Add one value to the indicated pattern attribute. The names of + attributes are the same as the ToolTalk accessors used to set them + less the `tooltalk_pattern_' prefix and the `_add' suffix. For + example, the name of the attribute for the + `tt_pattern_disposition_add' attribute is `disposition'. The + `category' attribute is handled specially, since a pattern can only + be a member of one category (`TT_OBSERVE' or `TT_HANDLE'). + + Callbacks are handled slightly differently than in the C ToolTalk + API. The value of CALLBACK should be the name of a function of one + argument. It will be called each time the pattern matches an + incoming message. + + - Function: add-tooltalk-pattern-arg pattern mode vtype &optional value + Add one fully-specified argument to a ToolTalk pattern. MODE must + be one of `TT_IN', `TT_INOUT', or `TT_OUT'. VTYPE must be a + string. VALUE can be an integer, string or `nil'. If VALUE is an + integer then an integer argument (`tt_pattern_iarg_add') is added; + otherwise a string argument is added. At present there's no way + to add a binary data argument. + + + - Function: create-tooltalk-pattern + Create a new ToolTalk pattern and initialize its session attribute + to be the default session. + + - Function: destroy-tooltalk-pattern pattern + Apply `tt_pattern_destroy' to the pattern. This effectively + unregisters the pattern. + + - Function: describe-tooltalk-message msg &optional stream + Print the message's attributes and arguments to STREAM. This is + often useful for debugging.  -File: lispref.info, Node: Calling CCL, Next: CCL Examples, Prev: CCL Expressions, Up: CCL - -Calling CCL ------------ - - CCL programs are called automatically during Emacs buffer I/O when -the external representation has a coding system type of `shift-jis', -`big5', or `ccl'. The program is specified by the coding system (*note -Coding Systems::). You can also call CCL programs from other CCL -programs, and from Lisp using these functions: - - - Function: ccl-execute ccl-program status - Execute CCL-PROGRAM with registers initialized by STATUS. - CCL-PROGRAM is a vector of compiled CCL code created by - `ccl-compile'. It is an error for the program to try to execute a - CCL I/O command. STATUS must be a vector of nine values, - specifying the initial value for the R0, R1 .. R7 registers and - for the instruction counter IC. A `nil' value for a register - initializer causes the register to be set to 0. A `nil' value for - the IC initializer causes execution to start at the beginning of - the program. When the program is done, STATUS is modified (by - side-effect) to contain the ending values for the corresponding - registers and IC. - - - Function: ccl-execute-on-string ccl-program status str &optional - continue - Execute CCL-PROGRAM with initial STATUS on STRING. CCL-PROGRAM is - a vector of compiled CCL code created by `ccl-compile'. STATUS - must be a vector of nine values, specifying the initial value for - the R0, R1 .. R7 registers and for the instruction counter IC. A - `nil' value for a register initializer causes the register to be - set to 0. A `nil' value for the IC initializer causes execution - to start at the beginning of the program. An optional fourth - argument CONTINUE, if non-nil, causes the IC to remain on the - unsatisfied read operation if the program terminates due to - exhaustion of the input buffer. Otherwise the IC is set to the end - of the program. When the program is done, STATUS is modified (by - side-effect) to contain the ending values for the corresponding - registers and IC. Returns the resulting string. - - To call a CCL program from another CCL program, it must first be -registered: - - - Function: register-ccl-program name ccl-program - Register NAME for CCL program PROGRAM in `ccl-program-table'. - PROGRAM should be the compiled form of a CCL program, or nil. - Return index number of the registered CCL program. - - Information about the processor time used by the CCL interpreter can -be obtained using these functions: - - - Function: ccl-elapsed-time - Returns the elapsed processor time of the CCL interpreter as cons - of user and system time, as floating point numbers measured in - seconds. If only one overall value can be determined, the return - value will be a cons of that value and 0. - - - Function: ccl-reset-elapsed-time - Resets the CCL interpreter's internal elapsed time registers. +File: lispref.info, Node: LDAP Support, Next: PostgreSQL Support, Prev: ToolTalk Support, Up: Top + +LDAP Support +************ + + XEmacs can be linked with a LDAP client library to provide Elisp +primitives to access directory servers using the Lightweight Directory +Access Protocol. + +* Menu: + +* Building XEmacs with LDAP support:: How to add LDAP support to XEmacs +* XEmacs LDAP API:: Lisp access to LDAP functions +* Syntax of Search Filters:: A brief summary of RFC 1558  -File: lispref.info, Node: CCL Examples, Prev: Calling CCL, Up: CCL +File: lispref.info, Node: Building XEmacs with LDAP support, Next: XEmacs LDAP API, Prev: LDAP Support, Up: LDAP Support + +Building XEmacs with LDAP support +================================= + + LDAP support must be added to XEmacs at build time since it requires +linking to an external LDAP client library. As of 21.2, XEmacs has been +successfully built and tested with + + * OpenLDAP 1.2 () + + * University of Michigan's LDAP 3.3 + () + + * LDAP SDK 1.0 from Netscape Corp. () -CCL Examples ------------- + Other libraries conforming to RFC 1823 will probably work also but +may require some minor tweaking at C level. - This section is not yet written. + The standard XEmacs configure script auto-detects an installed LDAP +library provided the library itself and the corresponding header files +can be found in the library and include paths. A successful detection +will be signalled in the final output of the configure script.  -File: lispref.info, Node: Category Tables, Prev: CCL, Up: MULE +File: lispref.info, Node: XEmacs LDAP API, Next: Syntax of Search Filters, Prev: Building XEmacs with LDAP support, Up: LDAP Support -Category Tables +XEmacs LDAP API =============== - A category table is a type of char table used for keeping track of -categories. Categories are used for classifying characters for use in -regexps - you can refer to a category rather than having to use a -complicated [] expression (and category lookups are significantly -faster). - - There are 95 different categories available, one for each printable -character (including space) in the ASCII charset. Each category is -designated by one such character, called a "category designator". They -are specified in a regexp using the syntax `\cX', where X is a category -designator. (This is not yet implemented.) - - A category table specifies, for each character, the categories that -the character is in. Note that a character can be in more than one -category. More specifically, a category table maps from a character to -either the value `nil' (meaning the character is in no categories) or a -95-element bit vector, specifying for each of the 95 categories whether -the character is in that category. - - Special Lisp functions are provided that abstract this, so you do not -have to directly manipulate bit vectors. - - - Function: category-table-p obj - This function returns `t' if ARG is a category table. - - - Function: category-table &optional buffer - This function returns the current category table. This is the one - specified by the current buffer, or by BUFFER if it is non-`nil'. - - - Function: standard-category-table - This function returns the standard category table. This is the - one used for new buffers. - - - Function: copy-category-table &optional table - This function constructs a new category table and return it. It - is a copy of the TABLE, which defaults to the standard category - table. - - - Function: set-category-table table &optional buffer - This function selects a new category table for BUFFER. One - argument, a category table. BUFFER defaults to the current buffer - if omitted. - - - Function: category-designator-p obj - This function returns `t' if ARG is a category designator (a char - in the range `' '' to `'~''). - - - Function: category-table-value-p obj - This function returns `t' if ARG is a category table value. Valid - values are `nil' or a bit vector of size 95. + XEmacs LDAP API consists of two layers: a low-level layer which +tries to stay as close as possible to the C API (where practical) and a +higher-level layer which provides more convenient primitives to +effectively use LDAP. + + The low-level API should be used directly for very specific purposes +(such as multiple operations on a connection) only. The higher-level +functions provide a more convenient way to access LDAP directories +hiding the subtleties of handling the connection, translating arguments +and ensuring compliance with LDAP internationalization rules and formats +(currently partly implemented only). + +* Menu: + +* LDAP Variables:: Lisp variables related to LDAP +* The High-Level LDAP API:: High-level LDAP lisp functions +* The Low-Level LDAP API:: Low-level LDAP lisp primitives +* LDAP Internationalization:: I18n variables and functions  -File: lispref.info, Node: Tips, Next: Building XEmacs and Object Allocation, Prev: MULE, Up: Top +File: lispref.info, Node: LDAP Variables, Next: The High-Level LDAP API, Prev: XEmacs LDAP API, Up: XEmacs LDAP API -Tips and Standards -****************** +LDAP Variables +-------------- - This chapter describes no additional features of XEmacs Lisp. -Instead it gives advice on making effective use of the features -described in the previous chapters. + - Variable: ldap-default-host + The default LDAP server hostname. A TCP port number can be + appended to that name using a colon as a separator. + + - Variable: ldap-default-port + Default TCP port for LDAP connections. Initialized from the LDAP + library. Default value is 389. + + - Variable: ldap-default-base + Default base for LDAP searches. This is a string using the syntax + of RFC 1779. For instance, "o=ACME, c=US" limits the search to the + Acme organization in the United States. + + - Variable: ldap-host-parameters-alist + An alist of per host options for LDAP transactions. The list + elements look like `(HOST PROP1 VAL1 PROP2 VAL2 ...)' HOST is the + name of an LDAP server. A TCP port number can be appended to that + name using a colon as a separator. PROPN and VALN are + property/value pairs describing parameters for the server. Valid + properties: + `binddn' + The distinguished name of the user to bind as. This may look + like `cn=Babs Jensen,o=ACME,c=US', see RFC 1779 for details. + + `passwd' + The password to use for authentication. + + `auth' + The authentication method to use, possible values depend on + the LDAP library XEmacs was compiled with, they may include + `simple', `krbv41' and `krbv42'. + + `base' + The base for the search. This may look like `cÿ, o¬me', see + RFC 1779 for syntax details. + + `scope' + One of the symbols `base', `onelevel' or `subtree' indicating + the scope of the search limited to a base object, to a single + level or to the whole subtree. + + `deref' + The dereference policy is one of the symbols `never', + `always', `search' or `find' and defines how aliases are + dereferenced. + `never' + Aliases are never dereferenced + + `always' + Aliases are always dereferenced + + `search' + Aliases are dereferenced when searching + + `find' + Aliases are dereferenced when locating the base object + for the search + + `timelimit' + The timeout limit for the connection in seconds. + + `sizelimit' + The maximum number of matches to return for searches + performed on this connection. + + - Variable: ldap-verbose + If non-`nil', LDAP operations will echo progress messages. + Defaults to `nil'. + + +File: lispref.info, Node: The High-Level LDAP API, Next: The Low-Level LDAP API, Prev: LDAP Variables, Up: XEmacs LDAP API + +The High-Level LDAP API +----------------------- + + The following functions provide the most convenient interface to +perform LDAP operations. All of them open a connection to a host, +perform an operation (add/search/modify/delete) on one or several +entries and cleanly close the connection thus insulating the user from +all the details of the low-level interface such as LDAP Lisp objects +*note The Low-Level LDAP API::. + + Note that `ldap-search' which used to be the name of the high-level +search function in XEmacs 21.1 is now obsolete. For consistency in the +naming as well as backward compatibility, that function now acts as a +wrapper that calls either `ldap-search-basic' (low-level search +function) or `ldap-search-entries' (high-level search function) +according to the actual parameters. A direct call to one of these two +functions is preferred since it is faster and unambiguous. + + - Command: ldap-search-entries filter &optional host attributes + attrsonly withdn + Perform an LDAP search. FILTER is the search filter *note Syntax + of Search Filters:: HOST is the LDAP host on which to perform the + search. ATTRIBUTES is the specific attributes to retrieve, `nil' + means retrieve all. ATTRSONLY if non-`nil' retrieves the + attributes only without their associated values. If WITHDN is + non-`nil' each entry in the result will be prepended with its + distinguished name DN. Additional search parameters can be + specified through `ldap-host-parameters-alist'. The function + returns a list of matching entries. Each entry is itself an alist + of attribute/value pairs optionally preceded by the DN of the + entry according to the value of WITHDN. + + - Function: ldap-add-entries entries &optional host binddn passwd + Add entries to an LDAP directory. ENTRIES is a list of entry + specifications of the form `(DN (ATTR . VALUE) (ATTR . VALUE) ...)' + where DN the distinguished name of an entry to add, the following + are cons cells containing attribute/value string pairs. HOST is + the LDAP host, defaulting to `ldap-default-host'. BINDDN is the + DN to bind as to the server. PASSWD is the corresponding password. + + - Function: ldap-modify-entries entry-mods &optional host binddn passwd + Modify entries of an LDAP directory. ENTRY_MODS is a list of + entry modifications of the form `(DN MOD-SPEC1 MOD-SPEC2 ...)' + where DN is the distinguished name of the entry to modify, the + following are modification specifications. A modification + specification is itself a list of the form `(MOD-OP ATTR VALUE1 + VALUE2 ...)' MOD-OP and ATTR are mandatory, VALUES are optional + depending on MOD-OP. MOD-OP is the type of modification, one of + the symbols `add', `delete' or `replace'. ATTR is the LDAP + attribute type to modify. HOST is the LDAP host, defaulting to + `ldap-default-host'. BINDDN is the DN to bind as to the server. + PASSWD is the corresponding password. + + - Function: ldap-delete-entries dn &optional host binddn passwd + Delete an entry from an LDAP directory. DN is the distinguished + name of an entry to delete or a list of those. HOST is the LDAP + host, defaulting to `ldap-default-host'. BINDDN is the DN to bind + as to the server. PASSWD is the corresponding password. + + +File: lispref.info, Node: The Low-Level LDAP API, Next: LDAP Internationalization, Prev: The High-Level LDAP API, Up: XEmacs LDAP API + +The Low-Level LDAP API +---------------------- + + The low-level API should be used directly for very specific purposes +(such as multiple operations on a connection) only. The higher-level +functions provide a more convenient way to access LDAP directories +hiding the subtleties of handling the connection, translating arguments +and ensuring compliance with LDAP internationalization rules and formats +(currently partly implemented only). See *note The High-Level LDAP API:: + + Note that the former functions `ldap-*-internal' functions have been +renamed in XEmacs 21.2 * Menu: -* Style Tips:: Writing clean and robust programs. -* Compilation Tips:: Making compiled code run fast. -* Documentation Tips:: Writing readable documentation strings. -* Comment Tips:: Conventions for writing comments. -* Library Headers:: Standard headers for library packages. +* The LDAP Lisp Object:: +* Opening and Closing a LDAP Connection:: +* Low-level Operations on a LDAP Server::  -File: lispref.info, Node: Style Tips, Next: Compilation Tips, Up: Tips +File: lispref.info, Node: The LDAP Lisp Object, Next: Opening and Closing a LDAP Connection, Prev: The Low-Level LDAP API, Up: The Low-Level LDAP API -Writing Clean Lisp Programs -=========================== +The LDAP Lisp Object +.................... + + An internal built-in `ldap' lisp object represents a LDAP connection. - Here are some tips for avoiding common errors in writing Lisp code -intended for widespread use: - - * Since all global variables share the same name space, and all - functions share another name space, you should choose a short word - to distinguish your program from other Lisp programs. Then take - care to begin the names of all global variables, constants, and - functions with the chosen prefix. This helps avoid name conflicts. - - This recommendation applies even to names for traditional Lisp - primitives that are not primitives in XEmacs Lisp--even to `cadr'. - Believe it or not, there is more than one plausible way to define - `cadr'. Play it safe; append your name prefix to produce a name - like `foo-cadr' or `mylib-cadr' instead. - - If you write a function that you think ought to be added to Emacs - under a certain name, such as `twiddle-files', don't call it by - that name in your program. Call it `mylib-twiddle-files' in your - program, and send mail to `bug-gnu-emacs@prep.ai.mit.edu' - suggesting we add it to Emacs. If and when we do, we can change - the name easily enough. - - If one prefix is insufficient, your package may use two or three - alternative common prefixes, so long as they make sense. - - Separate the prefix from the rest of the symbol name with a hyphen, - `-'. This will be consistent with XEmacs itself and with most - Emacs Lisp programs. - - * It is often useful to put a call to `provide' in each separate - library program, at least if there is more than one entry point to - the program. - - * If a file requires certain other library programs to be loaded - beforehand, then the comments at the beginning of the file should - say so. Also, use `require' to make sure they are loaded. - - * If one file FOO uses a macro defined in another file BAR, FOO - should contain this expression before the first use of the macro: - - (eval-when-compile (require 'BAR)) - - (And BAR should contain `(provide 'BAR)', to make the `require' - work.) This will cause BAR to be loaded when you byte-compile - FOO. Otherwise, you risk compiling FOO without the necessary - macro loaded, and that would produce compiled code that won't work - right. *Note Compiling Macros::. - - Using `eval-when-compile' avoids loading BAR when the compiled - version of FOO is _used_. - - * If you define a major mode, make sure to run a hook variable using - `run-hooks', just as the existing major modes do. *Note Hooks::. - - * If the purpose of a function is to tell you whether a certain - condition is true or false, give the function a name that ends in - `p'. If the name is one word, add just `p'; if the name is - multiple words, add `-p'. Examples are `framep' and - `frame-live-p'. - - * If a user option variable records a true-or-false condition, give - it a name that ends in `-flag'. - - * Please do not define `C-c LETTER' as a key in your major modes. - These sequences are reserved for users; they are the *only* - sequences reserved for users, so we cannot do without them. - - Instead, define sequences consisting of `C-c' followed by a - non-letter. These sequences are reserved for major modes. + - Function: ldapp object + This function returns non-`nil' if OBJECT is a `ldap' object. - Changing all the major modes in Emacs 18 so they would follow this - convention was a lot of work. Abandoning this convention would - make that work go to waste, and inconvenience users. + - Function: ldap-host ldap + Return the server host of the connection represented by LDAP. - * Sequences consisting of `C-c' followed by `{', `}', `<', `>', `:' - or `;' are also reserved for major modes. - - * Sequences consisting of `C-c' followed by any other punctuation - character are allocated for minor modes. Using them in a major - mode is not absolutely prohibited, but if you do that, the major - mode binding may be shadowed from time to time by minor modes. - - * You should not bind `C-h' following any prefix character (including - `C-c'). If you don't bind `C-h', it is automatically available as - a help character for listing the subcommands of the prefix - character. - - * You should not bind a key sequence ending in except following - another . (That is, it is ok to bind a sequence ending in - ` '.) - - The reason for this rule is that a non-prefix binding for in - any context prevents recognition of escape sequences as function - keys in that context. - - * Applications should not bind mouse events based on button 1 with - the shift key held down. These events include `S-mouse-1', - `M-S-mouse-1', `C-S-mouse-1', and so on. They are reserved for - users. - - * Modes should redefine `mouse-2' as a command to follow some sort of - reference in the text of a buffer, if users usually would not want - to alter the text in that buffer by hand. Modes such as Dired, - Info, Compilation, and Occur redefine it in this way. - - * When a package provides a modification of ordinary Emacs behavior, - it is good to include a command to enable and disable the feature, - Provide a command named `WHATEVER-mode' which turns the feature on - or off, and make it autoload (*note Autoload::). Design the - package so that simply loading it has no visible effect--that - should not enable the feature. Users will request the feature by - invoking the command. - - * It is a bad idea to define aliases for the Emacs primitives. Use - the standard names instead. - - * Redefining an Emacs primitive is an even worse idea. It may do - the right thing for a particular program, but there is no telling - what other programs might break as a result. - - * If a file does replace any of the functions or library programs of - standard XEmacs, prominent comments at the beginning of the file - should say which functions are replaced, and how the behavior of - the replacements differs from that of the originals. - - * Please keep the names of your XEmacs Lisp source files to 13 - characters or less. This way, if the files are compiled, the - compiled files' names will be 14 characters or less, which is - short enough to fit on all kinds of Unix systems. - - * Don't use `next-line' or `previous-line' in programs; nearly - always, `forward-line' is more convenient as well as more - predictable and robust. *Note Text Lines::. - - * Don't call functions that set the mark, unless setting the mark is - one of the intended features of your program. The mark is a - user-level feature, so it is incorrect to change the mark except - to supply a value for the user's benefit. *Note The Mark::. - - In particular, don't use these functions: - - * `beginning-of-buffer', `end-of-buffer' - - * `replace-string', `replace-regexp' - - If you just want to move point, or replace a certain string, - without any of the other features intended for interactive users, - you can replace these functions with one or two lines of simple - Lisp code. - - * Use lists rather than vectors, except when there is a particular - reason to use a vector. Lisp has more facilities for manipulating - lists than for vectors, and working with lists is usually more - convenient. - - Vectors are advantageous for tables that are substantial in size - and are accessed in random order (not searched front to back), - provided there is no need to insert or delete elements (only lists - allow that). - - * The recommended way to print a message in the echo area is with - the `message' function, not `princ'. *Note The Echo Area::. - - * When you encounter an error condition, call the function `error' - (or `signal'). The function `error' does not return. *Note - Signaling Errors::. - - Do not use `message', `throw', `sleep-for', or `beep' to report - errors. - - * An error message should start with a capital letter but should not - end with a period. - - * Try to avoid using recursive edits. Instead, do what the Rmail `e' - command does: use a new local keymap that contains one command - defined to switch back to the old local keymap. Or do what the - `edit-options' command does: switch to another buffer and let the - user switch back at will. *Note Recursive Editing::. - - * In some other systems there is a convention of choosing variable - names that begin and end with `*'. We don't use that convention - in Emacs Lisp, so please don't use it in your programs. (Emacs - uses such names only for program-generated buffers.) The users - will find Emacs more coherent if all libraries use the same - conventions. - - * Indent each function with `C-M-q' (`indent-sexp') using the - default indentation parameters. - - * Don't make a habit of putting close-parentheses on lines by - themselves; Lisp programmers find this disconcerting. Once in a - while, when there is a sequence of many consecutive - close-parentheses, it may make sense to split them in one or two - significant places. - - * Please put a copyright notice on the file if you give copies to - anyone. Use the same lines that appear at the top of the Lisp - files in XEmacs itself. If you have not signed papers to assign - the copyright to the Foundation, then place your name in the - copyright notice in place of the Foundation's name. + - Function: ldap-live-p ldap + Return non-`nil' if LDAP is an active LDAP connection.  -File: lispref.info, Node: Compilation Tips, Next: Documentation Tips, Prev: Style Tips, Up: Tips - -Tips for Making Compiled Code Fast -================================== - - Here are ways of improving the execution speed of byte-compiled Lisp -programs. - - * Use the `profile' library to profile your program. See the file - `profile.el' for instructions. - - * Use iteration rather than recursion whenever possible. Function - calls are slow in XEmacs Lisp even when a compiled function is - calling another compiled function. - - * Using the primitive list-searching functions `memq', `member', - `assq', or `assoc' is even faster than explicit iteration. It may - be worth rearranging a data structure so that one of these - primitive search functions can be used. - - * Certain built-in functions are handled specially in byte-compiled - code, avoiding the need for an ordinary function call. It is a - good idea to use these functions rather than alternatives. To see - whether a function is handled specially by the compiler, examine - its `byte-compile' property. If the property is non-`nil', then - the function is handled specially. - - For example, the following input will show you that `aref' is - compiled specially (*note Array Functions::) while `elt' is not - (*note Sequence Functions::): - - (get 'aref 'byte-compile) - => byte-compile-two-args - - (get 'elt 'byte-compile) - => nil - - * If calling a small function accounts for a substantial part of - your program's running time, make the function inline. This - eliminates the function call overhead. Since making a function - inline reduces the flexibility of changing the program, don't do - it unless it gives a noticeable speedup in something slow enough - that users care about the speed. *Note Inline Functions::. +File: lispref.info, Node: Opening and Closing a LDAP Connection, Next: Low-level Operations on a LDAP Server, Prev: The LDAP Lisp Object, Up: The Low-Level LDAP API + +Opening and Closing a LDAP Connection +..................................... + + - Function: ldap-open host &optional plist + Open a LDAP connection to HOST. PLIST is a property list + containing additional parameters for the connection. Valid keys + in that list are: + `port' + The TCP port to use for the connection if different from + `ldap-default-port' or the library builtin value + + `auth' + The authentication method to use, possible values depend on + the LDAP library XEmacs was compiled with, they may include + `simple', `krbv41' and `krbv42'. + + `binddn' + The distinguished name of the user to bind as. This may look + like `c=com, o=Acme, cn=Babs Jensen', see RFC 1779 for + details. + + `passwd' + The password to use for authentication. + + `deref' + The dereference policy is one of the symbols `never', + `always', `search' or `find' and defines how aliases are + dereferenced. + `never' + Aliases are never dereferenced. + + `always' + Aliases are always dereferenced. + + `search' + Aliases are dereferenced when searching. + + `find' + Aliases are dereferenced when locating the base object + for the search. The default is `never'. + + `timelimit' + The timeout limit for the connection in seconds. + + `sizelimit' + The maximum number of matches to return for searches + performed on this connection. + + - Function: ldap-close ldap + Close the connection represented by LDAP.  -File: lispref.info, Node: Documentation Tips, Next: Comment Tips, Prev: Compilation Tips, Up: Tips - -Tips for Documentation Strings -============================== - - Here are some tips for the writing of documentation strings. - - * Every command, function, or variable intended for users to know - about should have a documentation string. - - * An internal variable or subroutine of a Lisp program might as well - have a documentation string. In earlier Emacs versions, you could - save space by using a comment instead of a documentation string, - but that is no longer the case. - - * The first line of the documentation string should consist of one - or two complete sentences that stand on their own as a summary. - `M-x apropos' displays just the first line, and if it doesn't - stand on its own, the result looks bad. In particular, start the - first line with a capital letter and end with a period. - - The documentation string can have additional lines that expand on - the details of how to use the function or variable. The - additional lines should be made up of complete sentences also, but - they may be filled if that looks good. - - * For consistency, phrase the verb in the first sentence of a - documentation string as an infinitive with "to" omitted. For - instance, use "Return the cons of A and B." in preference to - "Returns the cons of A and B." Usually it looks good to do - likewise for the rest of the first paragraph. Subsequent - paragraphs usually look better if they have proper subjects. - - * Write documentation strings in the active voice, not the passive, - and in the present tense, not the future. For instance, use - "Return a list containing A and B." instead of "A list containing - A and B will be returned." - - * Avoid using the word "cause" (or its equivalents) unnecessarily. - Instead of, "Cause Emacs to display text in boldface," write just - "Display text in boldface." - - * Do not start or end a documentation string with whitespace. - - * Format the documentation string so that it fits in an Emacs window - on an 80-column screen. It is a good idea for most lines to be no - wider than 60 characters. The first line can be wider if - necessary to fit the information that ought to be there. - - However, rather than simply filling the entire documentation - string, you can make it much more readable by choosing line breaks - with care. Use blank lines between topics if the documentation - string is long. - - * *Do not* indent subsequent lines of a documentation string so that - the text is lined up in the source code with the text of the first - line. This looks nice in the source code, but looks bizarre when - users view the documentation. Remember that the indentation - before the starting double-quote is not part of the string! - - * A variable's documentation string should start with `*' if the - variable is one that users would often want to set interactively. - If the value is a long list, or a function, or if the variable - would be set only in init files, then don't start the - documentation string with `*'. *Note Defining Variables::. - - * The documentation string for a variable that is a yes-or-no flag - should start with words such as "Non-nil means...", to make it - clear that all non-`nil' values are equivalent and indicate - explicitly what `nil' and non-`nil' mean. - - * When a function's documentation string mentions the value of an - argument of the function, use the argument name in capital letters - as if it were a name for that value. Thus, the documentation - string of the function `/' refers to its second argument as - `DIVISOR', because the actual argument name is `divisor'. - - Also use all caps for meta-syntactic variables, such as when you - show the decomposition of a list or vector into subunits, some of - which may vary. - - * When a documentation string refers to a Lisp symbol, write it as it - would be printed (which usually means in lower case), with - single-quotes around it. For example: `lambda'. There are two - exceptions: write t and nil without single-quotes. (In this - manual, we normally do use single-quotes for those symbols.) - - * Don't write key sequences directly in documentation strings. - Instead, use the `\\[...]' construct to stand for them. For - example, instead of writing `C-f', write `\\[forward-char]'. When - Emacs displays the documentation string, it substitutes whatever - key is currently bound to `forward-char'. (This is normally `C-f', - but it may be some other character if the user has moved key - bindings.) *Note Keys in Documentation::. - - * In documentation strings for a major mode, you will want to refer - to the key bindings of that mode's local map, rather than global - ones. Therefore, use the construct `\\<...>' once in the - documentation string to specify which key map to use. Do this - before the first use of `\\[...]'. The text inside the `\\<...>' - should be the name of the variable containing the local keymap for - the major mode. - - It is not practical to use `\\[...]' very many times, because - display of the documentation string will become slow. So use this - to describe the most important commands in your major mode, and - then use `\\{...}' to display the rest of the mode's keymap. +File: lispref.info, Node: Low-level Operations on a LDAP Server, Prev: Opening and Closing a LDAP Connection, Up: The Low-Level LDAP API + +Low-level Operations on a LDAP Server +..................................... + + `ldap-search-basic' is the low-level primitive to perform a search +on a LDAP server. It works directly on an open LDAP connection thus +requiring a preliminary call to `ldap-open'. Multiple searches can be +made on the same connection, then the session must be closed with +`ldap-close'. + + - Function: ldap-search-basic ldap filter &optional base scope attrs + attrsonly withdn verbose + Perform a search on an open connection LDAP created with + `ldap-open'. FILTER is a filter string for the search *note + Syntax of Search Filters:: BASE is the distinguished name at which + to start the search. SCOPE is one of the symbols `base', + `onelevel' or `subtree' indicating the scope of the search limited + to a base object, to a single level or to the whole subtree. The + default is `subtree'. ATTRS is a list of strings indicating which + attributes to retrieve for each matching entry. If `nil' all + available attributes are returned. If ATTRSONLY is non-`nil' then + only the attributes are retrieved, not their associated values. + If WITHDN is non-`nil' then each entry in the result is prepended + with its distinguished name DN. If VERBOSE is non-`nil' then + progress messages are echoed The function returns a list of + matching entries. Each entry is itself an alist of + attribute/value pairs optionally preceded by the DN of the entry + according to the value of WITHDN. + + - Function: ldap-add ldap dn entry + Add ENTRY to a LDAP directory which a connection LDAP has been + opened to with `ldap-open'. DN is the distinguished name of the + entry to add. ENTRY is an entry specification, i.e., a list of + cons cells containing attribute/value string pairs. + + - Function: ldap-modify ldap dn mods + Modify an entry in an LDAP directory. LDAP is an LDAP connection + object created with `ldap-open'. DN is the distinguished name of + the entry to modify. MODS is a list of modifications to apply. A + modification is a list of the form `(MOD-OP ATTR VALUE1 VALUE2 + ...)' MOD-OP and ATTR are mandatory, VALUES are optional + depending on MOD-OP. MOD-OP is the type of modification, one of + the symbols `add', `delete' or `replace'. ATTR is the LDAP + attribute type to modify. + + - Function: ldap-delete ldap dn + Delete an entry to an LDAP directory. LDAP is an LDAP connection + object created with `ldap-open'. DN is the distinguished name of + the entry to delete.  -File: lispref.info, Node: Comment Tips, Next: Library Headers, Prev: Documentation Tips, Up: Tips +File: lispref.info, Node: LDAP Internationalization, Prev: The Low-Level LDAP API, Up: XEmacs LDAP API -Tips on Writing Comments -======================== +LDAP Internationalization +------------------------- - We recommend these conventions for where to put comments and how to -indent them: - -`;' - Comments that start with a single semicolon, `;', should all be - aligned to the same column on the right of the source code. Such - comments usually explain how the code on the same line does its - job. In Lisp mode and related modes, the `M-;' - (`indent-for-comment') command automatically inserts such a `;' in - the right place, or aligns such a comment if it is already present. - - This and following examples are taken from the Emacs sources. - - (setq base-version-list ; there was a base - (assoc (substring fn 0 start-vn) ; version to which - file-version-assoc-list)) ; this looks like - ; a subversion - -`;;' - Comments that start with two semicolons, `;;', should be aligned to - the same level of indentation as the code. Such comments usually - describe the purpose of the following lines or the state of the - program at that point. For example: - - (prog1 (setq auto-fill-function - ... - ... - ;; update modeline - (redraw-modeline))) - - Every function that has no documentation string (because it is use - only internally within the package it belongs to), should have - instead a two-semicolon comment right before the function, - explaining what the function does and how to call it properly. - Explain precisely what each argument means and how the function - interprets its possible values. - -`;;;' - Comments that start with three semicolons, `;;;', should start at - the left margin. Such comments are used outside function - definitions to make general statements explaining the design - principles of the program. For example: - - ;;; This Lisp code is run in XEmacs - ;;; when it is to operate as a server - ;;; for other processes. - - Another use for triple-semicolon comments is for commenting out - lines within a function. We use triple-semicolons for this - precisely so that they remain at the left margin. - - (defun foo (a) - ;;; This is no longer necessary. - ;;; (force-mode-line-update) - (message "Finished with %s" a)) - -`;;;;' - Comments that start with four semicolons, `;;;;', should be aligned - to the left margin and are used for headings of major sections of a - program. For example: - - ;;;; The kill ring - -The indentation commands of the Lisp modes in XEmacs, such as `M-;' -(`indent-for-comment') and (`lisp-indent-line') automatically -indent comments according to these conventions, depending on the number -of semicolons. *Note Manipulating Comments: (emacs)Comments. + The XEmacs LDAP API provides basic internationalization features +based on the LDAP v3 specification (essentially RFC2252 on "LDAP v3 +Attribute Syntax Definitions"). Unfortunately since there is currently +no free LDAP v3 server software, this part has not received much +testing and should be considered experimental. The framework is in +place though. + + - Function: ldap-decode-attribute attr + Decode the attribute/value pair ATTR according to LDAP rules. The + attribute name is looked up in `ldap-attribute-syntaxes-alist' and + the corresponding decoder is then retrieved from + `ldap-attribute-syntax-decoders'' and applied on the value(s). + +* Menu: + +* LDAP Internationalization Variables:: +* Encoder/Decoder Functions::  -File: lispref.info, Node: Library Headers, Prev: Comment Tips, Up: Tips +File: lispref.info, Node: LDAP Internationalization Variables, Next: Encoder/Decoder Functions, Prev: LDAP Internationalization, Up: LDAP Internationalization + +LDAP Internationalization Variables +................................... + + - Variable: ldap-ignore-attribute-codings + If non-`nil', no encoding/decoding will be performed LDAP + attribute values + + - Variable: ldap-coding-system + Coding system of LDAP string values. LDAP v3 specifies the coding + system of strings to be UTF-8. You need an XEmacs with Mule + support for this. + + - Variable: ldap-default-attribute-decoder + Decoder function to use for attributes whose syntax is unknown. + Such a function receives an encoded attribute value as a string + and should return the decoded value as a string. + + - Variable: ldap-attribute-syntax-encoders + A vector of functions used to encode LDAP attribute values. The + sequence of functions corresponds to the sequence of LDAP + attribute syntax object identifiers of the form + 1.3.6.1.4.1.1466.1115.121.1.* as defined in RFC2252 section 4.3.2. + As of this writing, only a few encoder functions are available. + + - Variable: ldap-attribute-syntax-decoders + A vector of functions used to decode LDAP attribute values. The + sequence of functions corresponds to the sequence of LDAP + attribute syntax object identifiers of the form + 1.3.6.1.4.1.1466.1115.121.1.* as defined in RFC2252 section 4.3.2. + As of this writing, only a few decoder functions are available. + + - Variable: ldap-attribute-syntaxes-alist + A map of LDAP attribute names to their type object id minor number. + This table is built from RFC2252 Section 5 and RFC2256 Section 5. -Conventional Headers for XEmacs Libraries -========================================= + +File: lispref.info, Node: Encoder/Decoder Functions, Prev: LDAP Internationalization Variables, Up: LDAP Internationalization - XEmacs has conventions for using special comments in Lisp libraries -to divide them into sections and give information such as who wrote -them. This section explains these conventions. First, an example: +Encoder/Decoder Functions +......................... - ;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers - - ;; Copyright (C) 1992 Free Software Foundation, Inc. - - ;; Author: Eric S. Raymond - ;; Maintainer: Eric S. Raymond - ;; Created: 14 Jul 1992 - ;; Version: 1.2 - ;; Keywords: docs - - ;; This file is part of XEmacs. - COPYING PERMISSIONS... + - Function: ldap-encode-boolean bool + A function that encodes an elisp boolean BOOL into a LDAP boolean + string representation. - The very first line should have this format: + - Function: ldap-decode-boolean str + A function that decodes a LDAP boolean string representation STR + into an elisp boolean. - ;;; FILENAME --- DESCRIPTION + - Function: ldap-decode-string str + Decode a string STR according to LDAP-CODING-SYSTEM. -The description should be complete in one line. + - Function: ldap-encode-string str + Encode a string STR according to LDAP-CODING-SYSTEM. - After the copyright notice come several "header comment" lines, each -beginning with `;; HEADER-NAME:'. Here is a table of the conventional -possibilities for HEADER-NAME: + - Function: ldap-decode-address str + Decode an address STR according to LDAP-CODING-SYSTEM and + replacing $ signs with newlines as specified by LDAP encoding + rules for addresses. -`Author' - This line states the name and net address of at least the principal - author of the library. + - Function: ldap-encode-address str + Encode an address STR according to LDAP-CODING-SYSTEM and + replacing newlines with $ signs as specified by LDAP encoding + rules for addresses. - If there are multiple authors, you can list them on continuation - lines led by `;;' and a tab character, like this: + +File: lispref.info, Node: Syntax of Search Filters, Prev: XEmacs LDAP API, Up: LDAP Support - ;; Author: Ashwin Ram - ;; Dave Sill - ;; Dave Brennan - ;; Eric Raymond +Syntax of Search Filters +======================== -`Maintainer' - This line should contain a single name/address as in the Author - line, or an address only, or the string `FSF'. If there is no - maintainer line, the person(s) in the Author field are presumed to - be the maintainers. The example above is mildly bogus because the - maintainer line is redundant. + LDAP search functions use RFC1558 syntax to describe the search +filter. In that syntax simple filters have the form: - The idea behind the `Author' and `Maintainer' lines is to make - possible a Lisp function to "send mail to the maintainer" without - having to mine the name out by hand. + ( ) - Be sure to surround the network address with `<...>' if you - include the person's full name as well as the network address. + `' is an attribute name such as `cn' for Common Name, `o' for +Organization, etc... -`Created' - This optional line gives the original creation date of the file. - For historical interest only. + `' is the corresponding value. This is generally an exact +string but may also contain `*' characters as wildcards -`Version' - If you wish to record version numbers for the individual Lisp - program, put them in this line. + `filtertype' is one `=' `~=', `<=', `>=' which respectively describe +equality, approximate equality, inferiority and superiority. -`Adapted-By' - In this header line, place the name of the person who adapted the - library for installation (to make it fit the style conventions, for - example). + Thus `(cn=John Smith)' matches all records having a canonical name +equal to John Smith. -`Keywords' - This line lists keywords for the `finder-by-keyword' help command. - This field is important; it's how people will find your package - when they're looking for things by topic area. To separate the - keywords, you can use spaces, commas, or both. + A special case is the presence filter `(=*' which matches +records containing a particular attribute. For instance `(mail=*)' +matches all records containing a `mail' attribute. - Just about every Lisp library ought to have the `Author' and -`Keywords' header comment lines. Use the others if they are -appropriate. You can also put in header lines with other header -names--they have no standard meanings, so they can't do any harm. + Simple filters can be connected together with the logical operators +`&', `|' and `!' which stand for the usual and, or and not operators. - We use additional stylized comments to subdivide the contents of the -library file. Here is a table of them: + `(&(objectClass=Person)(mail=*)(|(sn=Smith)(givenname=John)))' +matches records of class `Person' containing a `mail' attribute and +corresponding to people whose last name is `Smith' or whose first name +is `John'. -`;;; Commentary:' - This begins introductory comments that explain how the library - works. It should come right after the copying permissions. + +File: lispref.info, Node: PostgreSQL Support, Next: Internationalization, Prev: LDAP Support, Up: Top -`;;; Change log:' - This begins change log information stored in the library file (if - you store the change history there). For most of the Lisp files - distributed with XEmacs, the change history is kept in the file - `ChangeLog' and not in the source file at all; these files do not - have a `;;; Change log:' line. +PostgreSQL Support +****************** -`;;; Code:' - This begins the actual code of the program. + XEmacs can be linked with PostgreSQL libpq run-time support to +provide relational database access from Emacs Lisp code. -`;;; FILENAME ends here' - This is the "footer line"; it appears at the very end of the file. - Its purpose is to enable people to detect truncated versions of - the file from the lack of a footer line. +* Menu: + +* Building XEmacs with PostgreSQL support:: +* XEmacs PostgreSQL libpq API:: +* XEmacs PostgreSQL libpq Examples::  -File: lispref.info, Node: Building XEmacs and Object Allocation, Next: Standard Errors, Prev: Tips, Up: Top +File: lispref.info, Node: Building XEmacs with PostgreSQL support, Next: XEmacs PostgreSQL libpq API, Up: PostgreSQL Support + +Building XEmacs with PostgreSQL support +======================================= -Building XEmacs; Allocation of Objects -************************************** + XEmacs PostgreSQL support requires linking to the PostgreSQL libpq +library. Describing how to build and install PostgreSQL is beyond the +scope of this document. See the PostgreSQL manual for details. - This chapter describes how the runnable XEmacs executable is dumped -with the preloaded Lisp libraries in it and how storage is allocated. + If you have installed XEmacs from one of the binary kits on +(), or are using an XEmacs binary from a CD ROM, +you may have XEmacs PostgreSQL support by default. `M-x +describe-installation' will tell you if you do. - There is an entire separate document, the `XEmacs Internals Manual', -devoted to the internals of XEmacs from the perspective of the C -programmer. It contains much more detailed information about the build -process, the allocation and garbage-collection process, and other -aspects related to the internals of XEmacs. + If you are building XEmacs from source, you need to install +PostgreSQL first. On some systems, PostgreSQL will come pre-installed +in /usr. In this case, it should be autodetected when you run +configure. If PostgreSQL is installed into its default location, +`/usr/local/pgsql', you must specify `--site-prefixes=/usr/local/pgsql' +when you run configure. If PostgreSQL is installed into another +location, use that instead of `/usr/local/pgsql' when specifying +`--site-prefixes'. + + As of XEmacs 21.2, PostgreSQL versions 6.5.3 and 7.0 are supported. +XEmacs Lisp support for V7.0 is somewhat more extensive than support for +V6.5. In particular, asynchronous queries are supported. + + +File: lispref.info, Node: XEmacs PostgreSQL libpq API, Next: XEmacs PostgreSQL libpq Examples, Prev: Building XEmacs with PostgreSQL support, Up: PostgreSQL Support + +XEmacs PostgreSQL libpq API +=========================== + + The XEmacs PostgreSQL API is intended to be a policy-free, low-level +binding to libpq. The intent is to provide all the basic functionality +and then let high level Lisp code decide its own policies. + + This documentation assumes that the reader has knowledge of SQL, but +requires no prior knowledge of libpq. + + There are many examples in this manual and some setup will be +required. In order to run most of the following examples, the +following code needs to be executed. In addition to the data is in +this table, nearly all of the examples will assume that the free +variable `P' refers to this database connection. The examples in the +original edition of this manual were run against Postgres 7.0beta1. + + (progn + (setq P (pq-connectdb "")) + ;; id is the primary key, shikona is a Japanese word that + ;; means `the professional name of a Sumo wrestler', and + ;; rank is the Sumo rank name. + (pq-exec P (concat "CREATE TABLE xemacs_test" + " (id int, shikona text, rank text);")) + (pq-exec P "COPY xemacs_test FROM stdin;") + (pq-put-line P "1\tMusashimaru\tYokuzuna\n") + (pq-put-line P "2\tDejima\tOozeki\n") + (pq-put-line P "3\tMusoyama\tSekiwake\n") + (pq-put-line P "4\tMiyabiyama\tSekiwake\n") + (pq-put-line P "5\tWakanoyama\tMaegashira\n") + (pq-put-line P "\\.\n") + (pq-end-copy P)) + => nil * Menu: -* Building XEmacs:: How to preload Lisp libraries into XEmacs. -* Pure Storage:: A kludge to make preloaded Lisp functions sharable. -* Garbage Collection:: Reclaiming space for Lisp objects no longer used. +* libpq Lisp Variables:: +* libpq Lisp Symbols and DataTypes:: +* Synchronous Interface Functions:: +* Asynchronous Interface Functions:: +* Large Object Support:: +* Other libpq Functions:: +* Unimplemented libpq Functions:: + + +File: lispref.info, Node: libpq Lisp Variables, Next: libpq Lisp Symbols and DataTypes, Prev: XEmacs PostgreSQL libpq API, Up: XEmacs PostgreSQL libpq API + +libpq Lisp Variables +-------------------- + + Various Unix environment variables are used by libpq to provide +defaults to the many different parameters. In the XEmacs Lisp API, +these environment variables are bound to Lisp variables to provide more +convenient access to Lisp Code. These variables are passed to the +backend database server during the establishment of a database +connection and when the `pq-setenv' call is made. + + - Variable: pg:host + Initialized from the PGHOST environment variable. The default + host to connect to. + + - Variable: pg:user + Initialized from the PGUSER environment variable. The default + database user name. + + - Variable: pg:options + Initialized from the PGOPTIONS environment variable. Default + additional server options. + + - Variable: pg:port + Initialized from the PGPORT environment variable. The default TCP + port to connect to. + + - Variable: pg:tty + Initialized from the PGTTY environment variable. The default + debugging TTY. + + Compatibility note: Debugging TTYs are turned off in the XEmacs + Lisp binding. + + - Variable: pg:database + Initialized from the PGDATABASE environment variable. The default + database to connect to. + + - Variable: pg:realm + Initialized from the PGREALM environment variable. The default + Kerberos realm. + + - Variable: pg:client-encoding + Initialized from the PGCLIENTENCODING environment variable. The + default client encoding. + + Compatibility note: This variable is not present in non-Mule + XEmacsen. This variable is not present in versions of libpq prior + to 7.0. In the current implementation, client encoding is + equivalent to the `file-name-coding-system' format. + + - Variable: pg:authtype + Initialized from the PGAUTHTYPE environment variable. The default + authentication scheme used. + + Compatibility note: This variable is unused in versions of libpq + after 6.5. It is not implemented at all in the XEmacs Lisp + binding. + + - Variable: pg:geqo + Initialized from the PGGEQO environment variable. Genetic + optimizer options. + + - Variable: pg:cost-index + Initialized from the PGCOSTINDEX environment variable. Cost index + options. + + - Variable: pg:cost-heap + Initialized from the PGCOSTHEAP environment variable. Cost heap + options. + + - Variable: pg:tz + Initialized from the PGTZ environment variable. Default timezone. + + - Variable: pg:date-style + Initialized from the PGDATESTYLE environment variable. Default + date style in returned date objects. + + - Variable: pg-coding-system + This is a variable controlling which coding system is used to + encode non-ASCII strings sent to the database. + + Compatibility Note: This variable is not present in InfoDock.