-This is ../info/lispref.info, produced by makeinfo version 3.12s from
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
Foundation instead of in the original English.
\1f
-File: lispref.info, Node: Big5 and Shift-JIS Functions, Prev: Detection of Textual Encoding, Up: Coding Systems
+File: lispref.info, Node: LDAP Variables, Next: The High-Level LDAP API, Prev: XEmacs LDAP API, Up: XEmacs LDAP API
-Big5 and Shift-JIS Functions
-----------------------------
+LDAP Variables
+--------------
- These are special functions for working with the non-standard
-Shift-JIS and Big5 encodings.
+ - 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'.
- - 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.
+\1f
+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.
+
+ - Function: 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.
- - 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.
+\1f
+File: lispref.info, Node: The Low-Level LDAP API, Next: LDAP Internationalization, Prev: The High-Level LDAP API, Up: XEmacs LDAP API
- - 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 Low-Level LDAP API
+----------------------
- - 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 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::
-\1f
-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).
+ Note that the former functions `ldap-*-internal' functions have been
+renamed in XEmacs 21.2
* 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.
+* The LDAP Lisp Object::
+* Opening and Closing a LDAP Connection::
+* Low-level Operations on a LDAP Server::
\1f
-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: The LDAP Lisp Object, Next: Opening and Closing a LDAP Connection, Prev: The Low-Level LDAP API, Up: The Low-Level LDAP API
+
+The LDAP Lisp Object
+....................
+
+ An internal built-in `ldap' lisp object represents a LDAP connection.
+
+ - Function: ldapp object
+ This function returns non-`nil' if OBJECT is a `ldap' object.
+
+ - Function: ldap-host ldap
+ Return the server host of the connection represented by LDAP
+
+ - Function: ldap-live-p ldap
+ Return non-`nil' if LDAP is an active LDAP connection
\1f
-File: lispref.info, Node: CCL Statements, Next: CCL Expressions, Prev: CCL Syntax, Up: CCL
+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
-CCL Statements
---------------
+Opening and Closing a LDAP Connection
+.....................................
- The Emacs Code Conversion Language provides the following statement
-types: "set", "if", "branch", "loop", "repeat", "break", "read",
-"write", "call", and "end".
-
-Set statement:
-==============
-
- 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)'.
-
-I/O statements:
-===============
-
- 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:
-========================
+ - 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
- 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.
+ `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
\1f
-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: 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 base scope attrs attrsonly
+ 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
+
+\1f
+File: lispref.info, Node: LDAP Internationalization, Prev: The Low-Level LDAP API, Up: XEmacs LDAP API
+
+LDAP Internationalization
+-------------------------
+
+ 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::
\1f
-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 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
\1f
-File: lispref.info, Node: CCL Examples, Prev: Calling CCL, Up: CCL
+File: lispref.info, Node: Encoder/Decoder Functions, Prev: LDAP Internationalization Variables, Up: LDAP Internationalization
+
+Encoder/Decoder Functions
+.........................
+
+ - Function: ldap-encode-boolean bool
+ A function that encodes an elisp boolean BOOL into a LDAP boolean
+ string representation
+
+ - Function: ldap-decode-boolean str
+ A function that decodes a LDAP boolean string representation STR
+ into an elisp boolean
+
+ - Function: ldap-decode-string str
+ Decode a string STR according to `ldap-coding-system'
-CCL Examples
-------------
+ - Function: ldap-encode-string str
+ Encode a string STR according to `ldap-coding-system'
- This section is not yet written.
+ - 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
+
+ - 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
\1f
-File: lispref.info, Node: Category Tables, Prev: CCL, Up: MULE
-
-Category Tables
-===============
-
- 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.
+File: lispref.info, Node: Syntax of Search Filters, Prev: XEmacs LDAP API, Up: LDAP Support
+
+Syntax of Search Filters
+========================
+
+ LDAP search functions use RFC1558 syntax to describe the search
+filter. In that syntax simple filters have the form:
+
+ (<attr> <filtertype> <value>)
+
+ `<attr>' is an attribute name such as `cn' for Common Name, `o' for
+Organization, etc...
+
+ `<value>' is the corresponding value. This is generally an exact
+string but may also contain `*' characters as wildcards
+
+ `filtertype' is one `=' `~=', `<=', `>=' which respectively describe
+equality, approximate equality, inferiority and superiority.
+
+ Thus `(cn=John Smith)' matches all records having a canonical name
+equal to John Smith.
+
+ A special case is the presence filter `(<attr>=*' which matches
+records containing a particular attribute. For instance `(mail=*)'
+matches all records containing a `mail' attribute.
+
+ Simple filters can be connected together with the logical operators
+`&', `|' and `!' which stand for the usual and, or and not operators.
+
+ `(&(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'.
\1f
-File: lispref.info, Node: Tips, Next: Building XEmacs and Object Allocation, Prev: MULE, Up: Top
+File: lispref.info, Node: PostgreSQL Support, Next: Internationalization, Prev: LDAP Support, Up: Top
-Tips and Standards
+PostgreSQL Support
******************
- 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.
+ XEmacs can be linked with PostgreSQL libpq run-time support to
+provide relational database access from Emacs Lisp code.
* 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.
+* Building XEmacs with PostgreSQL support::
+* XEmacs PostgreSQL libpq API::
+* XEmacs PostgreSQL libpq Examples::
\1f
-File: lispref.info, Node: Style Tips, Next: Compilation Tips, Up: Tips
+File: lispref.info, Node: Building XEmacs with PostgreSQL support, Next: XEmacs PostgreSQL libpq API, Up: PostgreSQL Support
+
+Building XEmacs with PostgreSQL support
+=======================================
+
+ 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.
+
+ If you have installed XEmacs from one of the binary kits on
+(<ftp://ftp.xemacs.org/>), 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.
+
+ 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'.
-Writing Clean Lisp Programs
+ 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.
+
+\1f
+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
===========================
- 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.
+ 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:
+
+* libpq Lisp Variables::
+* libpq Lisp Symbols and DataTypes::
+* Synchronous Interface Functions::
+* Asynchronous Interface Functions::
+* Large Object Support::
+* Other libpq Functions::
+* Unimplemented libpq Functions::
+
+\1f
+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.
- 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.
+ Compatibility note: Debugging TTYs are turned off in the XEmacs
+ Lisp binding.
- * 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 <ESC> except following
- another <ESC>. (That is, it is ok to bind a sequence ending in
- `<ESC> <ESC>'.)
-
- The reason for this rule is that a non-prefix binding for <ESC> 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.
+ - 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.
\1f
-File: lispref.info, Node: Compilation Tips, Next: Documentation Tips, Prev: Style Tips, Up: Tips
+File: lispref.info, Node: libpq Lisp Symbols and DataTypes, Next: Synchronous Interface Functions, Prev: libpq Lisp Variables, Up: XEmacs PostgreSQL libpq API
+
+libpq Lisp Symbols and Datatypes
+--------------------------------
+
+ The following set of symbols are used to represent the intermediate
+states involved in the asynchronous interface.
+
+ - Symbol: pgres::polling-failed
+ Undocumented. A fatal error has occurred during processing of an
+ asynchronous operation.
+
+ - Symbol: pgres::polling-reading
+ An intermediate status return during an asynchronous operation. It
+ indicates that one may use `select' before polling again.
+
+ - Symbol: pgres::polling-writing
+ An intermediate status return during an asynchronous operation. It
+ indicates that one may use `select' before polling again.
+
+ - Symbol: pgres::polling-ok
+ An asynchronous operation has successfully completed.
+
+ - Symbol: pgres::polling-active
+ An intermediate status return during an asynchronous operation.
+ One can call the poll function again immediately.
+
+ - 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
+
+ `pq::user'
+ Database user name
+
+ `pq::pass'
+ Database user's password
+
+ `pq::host'
+ Hostname database server is running on
+
+ `pq::port'
+ TCP port number used in the connection
+
+ `pq::tty'
+ Debugging TTY
+
+ Compatibility note: Debugging TTYs are not used in the
+ XEmacs Lisp API.
+
+ `pq::options'
+ Additional server options
+
+ `pq::status'
+ Connection status. Possible return values are shown in the
+ following table.
+ `pg::connection-ok'
+ The normal, connected status.
+
+ `pg::connection-bad'
+ The connection is not open and the PGconn object needs
+ to be deleted by `pq-finish'.
+
+ `pg::connection-started'
+ An asynchronous connection has been started, but is not
+ yet complete.
+
+ `pg::connection-made'
+ An asynchronous connect has been made, and there is data
+ waiting to be sent.
+
+ `pg::connection-awaiting-response'
+ Awaiting data from the backend during an asynchronous
+ connection.
-Tips for Making Compiled Code Fast
-==================================
+ `pg::connection-auth-ok'
+ Received authentication, waiting for the backend to
+ start up.
- Here are ways of improving the execution speed of byte-compiled Lisp
-programs.
+ `pg::connection-setenv'
+ Negotiating environment during an asynchronous
+ connection.
- * Use the `profile' library to profile your program. See the file
- `profile.el' for instructions.
+ `pq::error-message'
+ The last error message that was delivered to this connection.
- * Use iteration rather than recursion whenever possible. Function
- calls are slow in XEmacs Lisp even when a compiled function is
- calling another compiled function.
+ `pq::backend-pid'
+ The process ID of the backend database server.
- * 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.
+ 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:
- * 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.
+ (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
+ => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
- For example, the following input will show you that `aref' is
- compiled specially (*note Array Functions::) while `elt' is not
- (*note Sequence Functions::):
+ 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:
- (get 'aref 'byte-compile)
- => byte-compile-two-args
-
- (get 'elt 'byte-compile)
+ (pq-exec P "CREATE TABLE a_new_table (i int);")
+ => #<PGresult PGRES_COMMAND_OK - CREATE>
+
+ 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;")))
+ => #<PGresult PGRES_COMMAND_OK[3] - DELETE 3>
+
+ 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)
+ => #<PGresult DEAD>
+
+ 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;"))
+ => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
+ (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;"))
+ => <A fatal error is signaled in the echo area>
+ (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;"))
+ => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
+ (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;"))
+ => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
+ (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;"))
+ => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
+ (pq-binary-tuples R)
=> 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::.
+ - 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;"))
+ => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
+ (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;"))
+ => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
+ (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;"))
+ => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
+ (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');")
+ => #<PGresult PGRES_COMMAND_OK[1] - INSERT 542086 1>
+ (pq-cmd-status R)
+ => "INSERT 542086 1"
+ (setq R (pq-exec P "UPDATE xemacs_test SET rank='retired'
+ WHERE shikona='Wakanohana';"))
+ => #<PGresult PGRES_COMMAND_OK[1] - UPDATE 1>
+ (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');"))
+ => #<PGresult PGRES_COMMAND_OK[1] - INSERT 38688 1>
+ (pq-cmd-tuples R)
+ => "1"
+ (setq R (pq-exec P "SELECT * from xemacs_test;"))
+ => #<PGresult PGRES_TUPLES_OK[7] - SELECT>
+ (pq-cmd-tuples R)
+ => ""
+ (setq R (pq-exec P "DELETE FROM xemacs_test
+ WHERE shikona LIKE '%hana';"))
+ => #<PGresult PGRES_COMMAND_OK[2] - DELETE 2>
+ (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');"))
+ => #<PGresult PGRES_COMMAND_OK[1] - INSERT 542089 1>
+ (pq-oid-value R)
+ => 542089
+ (setq R (pq-exec P "SELECT shikona FROM xemacs_test
+ WHERE rank='Maegashira';"))
+ => #<PGresult PGRES_TUPLES_OK[2] - SELECT>
+ (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.
\1f
-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: 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")
+ => #<PGconn localhost:25432 steve/japanese>
+ 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:
+ #<PGconn BAD>
+ 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)
+ => #<PGconn DEAD>
+
+ 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.
+
+ `user'
+ Database user name. Same as PGUSER.
+
+ `password'
+ Database password.
+
+ `dbname'
+ Database name. Same as PGDATABASE
+
+ `host'
+ Symbolic hostname. Same as PGHOST.
+
+ `hostaddr'
+ Host address as four octets (eg. like 192.168.1.1).
+
+ `port'
+ TCP port to connect to. Same as PGPORT.
+
+ `tty'
+ Debugging TTY. Same as PGTTY. This value is suppressed in
+ the XEmacs Lisp API.
+
+ `options'
+ Extra backend database options. Same as PGOPTIONS. A
+ database connection object is returned regardless of whether a
+ connection was established or not.
+
+ - Function: pq-reset conn
+ Reestablish database connection. CONN A database connection
+ object.
+
+ 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.
+
+ - 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.
+
+ (setq R (pq-exec P "SELECT * FROM xemacs_test;
+ DELETE FROM xemacs_test WHERE id=8;"))
+ => #<PGresult PGRES_COMMAND_OK[1] - DELETE 1>
+
+ - 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.
+
+ - Function: PQsetenv conn
+ Synchronous transfer of environment variables to a backend CONN A
+ database connection object.
+
+ Environment variable transfer is done as a normal part of database
+ connection.
+
+ Compatibility note: This function was present but not documented
+ in versions of libpq prior to 7.0.
\1f
-File: lispref.info, Node: Comment Tips, Next: Library Headers, Prev: Documentation Tips, Up: Tips
+File: lispref.info, Node: Asynchronous Interface Functions, Next: Large Object Support, Prev: Synchronous Interface Functions, Up: XEmacs PostgreSQL libpq API
-Tips on Writing Comments
-========================
+Asynchronous Interface Functions
+--------------------------------
- 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 <TAB> (`lisp-indent-line') automatically
-indent comments according to these conventions, depending on the number
-of semicolons. *Note Manipulating Comments: (emacs)Comments.
+ Making command by command examples is too complex with the
+asynchronous interface functions. See the examples section for
+complete calling sequences.
-\1f
-File: lispref.info, Node: Library Headers, Prev: Comment Tips, Up: Tips
-
-Conventional Headers for XEmacs Libraries
-=========================================
-
- 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:
-
- ;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
-
- ;; Copyright (C) 1992 Free Software Foundation, Inc.
-
- ;; Author: Eric S. Raymond <esr@snark.thyrsus.com>
- ;; Maintainer: Eric S. Raymond <esr@snark.thyrsus.com>
- ;; Created: 14 Jul 1992
- ;; Version: 1.2
- ;; Keywords: docs
-
- ;; This file is part of XEmacs.
- COPYING PERMISSIONS...
-
- The very first line should have this format:
-
- ;;; FILENAME --- DESCRIPTION
-
-The description should be complete in one line.
-
- 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:
-
-`Author'
- This line states the name and net address of at least the principal
- author of the library.
-
- If there are multiple authors, you can list them on continuation
- lines led by `;;' and a tab character, like this:
-
- ;; Author: Ashwin Ram <Ram-Ashwin@cs.yale.edu>
- ;; Dave Sill <de5@ornl.gov>
- ;; Dave Brennan <brennan@hal.com>
- ;; Eric Raymond <esr@snark.thyrsus.com>
-
-`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.
-
- 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.
-
-`Created'
- This optional line gives the original creation date of the file.
- For historical interest only.
-
-`Version'
- If you wish to record version numbers for the individual Lisp
- program, put them in this line.
-
-`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).
-
-`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.
-
- 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.
-
- We use additional stylized comments to subdivide the contents of the
-library file. Here is a table of them:
-
-`;;; Commentary:'
- This begins introductory comments that explain how the library
- works. It should come right after the copying permissions.
-
-`;;; 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.
-
-`;;; Code:'
- This begins the actual code of the program.
-
-`;;; 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.
+ - 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.
+
+ - 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.
+
+ - Function: pq-is-busy conn
+ Returns t if `pq-get-result' would block waiting for input. CONN
+ A database connection object.
+
+ - Function: pq-consume-input conn
+ Consume any available input from the backend. CONN A database
+ connection object.
+
+ Nil is returned if anything bad happens.
+
+ - Function: pq-reset-start conn
+ Reset connection to the backend asynchronously. CONN A database
+ connection object.
+
+ - Function: pq-reset-poll conn
+ Poll an asynchronous reset for completion CONN A database
+ connection object.
+
+ - Function: pq-reset-cancel conn
+ Attempt to request cancellation of the current operation. CONN A
+ database connection object.
+
+ 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.
+
+ - 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)
+
+ - Function: pq-get-result conn
+ Retrieve an asynchronous result from a query. CONN A database
+ connection object.
+
+ NIL is returned when no more query work remains.
+
+ - 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.
+
+ - Function: pq-is-nonblocking conn
+ Return the blocking status of the database connection CONN A
+ database connection object.
+
+ - Function: pq-flush conn
+ Force the write buffer to be written (or at least try) CONN A
+ database connection object.
+
+ - Function: PQsetenvStart conn
+ Start asynchronously passing environment variables to a backend.
+ CONN A database connection object.
+
+ Compatibility note: this function is only available with libpq-7.0.
+
+ - Function: PQsetenvPoll conn
+ Check an asynchronous environment variables transfer for
+ completion. CONN A database connection object.
+
+ Compatibility note: this function is only available with libpq-7.0.
+
+ - Function: PQsetenvAbort conn
+ Attempt to terminate an asynchronous environment variables
+ transfer. CONN A database connection object.
+
+ Compatibility note: this function is only available with libpq-7.0.
\1f
-File: lispref.info, Node: Building XEmacs and Object Allocation, Next: Standard Errors, Prev: Tips, Up: Top
+File: lispref.info, Node: Large Object Support, Next: Other libpq Functions, Prev: Asynchronous Interface Functions, Up: XEmacs PostgreSQL libpq API
-Building XEmacs; Allocation of Objects
-**************************************
+Large Object Support
+--------------------
- This chapter describes how the runnable XEmacs executable is dumped
-with the preloaded Lisp libraries in it and how storage is allocated.
+ - 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
- 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.
+ On success, the object id is returned.
-* Menu:
+ - 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.
-* 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.
+\1f
+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.
projects / chise / xemacs-chise.git / blobdiff