Foundation instead of in the original English.
\1f
-File: lispref.info, Node: libpq Lisp Symbols and DataTypes, Next: Synchronous Interface Functions, Prev: libpq Lisp Variables, Up: XEmacs PostgreSQL libpq API
+File: lispref.info, Node: 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.
-libpq Lisp Symbols and Datatypes
---------------------------------
-
- The following set of symbols are used to represent the intermediate
-states involved in the asynchronous interface.
+\1f
+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
- - Symbol: pgres::polling-failed
- Undocumented. A fatal error has occurred during processing of an
- asynchronous operation.
+\1f
+File: lispref.info, Node: ToolTalk Support, Next: LDAP Support, Prev: X-Windows, Up: Top
- - Symbol: pgres::polling-reading
- An intermediate status return during an asynchronous operation. It
- indicates that one may use `select' before polling again.
+ToolTalk Support
+****************
- - Symbol: pgres::polling-writing
- An intermediate status return during an asynchronous operation. It
- indicates that one may use `select' before polling again.
+* Menu:
- - Symbol: pgres::polling-ok
- An asynchronous operation has successfully completed.
+* XEmacs ToolTalk API Summary::
+* Sending Messages::
+* Receiving Messages::
- - Symbol: pgres::polling-active
- An intermediate status return during an asynchronous operation.
- One can call the poll function again immediately.
+\1f
+File: lispref.info, Node: XEmacs ToolTalk API Summary, Next: Sending Messages, Up: ToolTalk Support
- - 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
+XEmacs ToolTalk API Summary
+===========================
- `pq::user'
- Database user name
+ 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:
- `pq::pass'
- Database user's password
+ * 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.
- `pq::host'
- Hostname database server is running on
+ * There are fewer entry points; polymorphic functions with keyword
+ arguments are used instead.
- `pq::port'
- TCP port number used in the connection
+ * 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).
- `pq::tty'
- Debugging TTY
+ * The session attribute for messages and patterns is always
+ initialized to the default session.
- Compatibility note: Debugging TTYs are not used in the
- XEmacs Lisp API.
+ * 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.
- `pq::options'
- Additional server options
+\1f
+File: lispref.info, Node: Sending Messages, Next: Receiving Messages, Prev: XEmacs ToolTalk API Summary, Up: ToolTalk Support
- `pq::status'
- Connection status. Possible return values are shown in the
- following table.
- `pg::connection-ok'
- The normal, connected status.
+Sending Messages
+================
- `pg::connection-bad'
- The connection is not open and the PGconn object needs
- to be deleted by `pq-finish'.
+* Menu:
- `pg::connection-started'
- An asynchronous connection has been started, but is not
- yet complete.
+* Example of Sending Messages::
+* Elisp Interface for Sending Messages::
- `pg::connection-made'
- An asynchronous connect has been made, and there is data
- waiting to be sent.
+\1f
+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))
- `pg::connection-awaiting-response'
- Awaiting data from the backend during an asynchronous
- connection.
+\1f
+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_<attribute>' 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.
- `pg::connection-auth-ok'
- Received authentication, waiting for the backend to
- start up.
+\1f
+File: lispref.info, Node: Receiving Messages, Prev: Sending Messages, Up: ToolTalk Support
- `pg::connection-setenv'
- Negotiating environment during an asynchronous
- connection.
+Receiving Messages
+==================
- `pq::error-message'
- The last error message that was delivered to this connection.
+* Menu:
- `pq::backend-pid'
- The process ID of the backend database server.
+* Example of Receiving Messages::
+* Elisp Interface for Receiving Messages::
- 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:
+\1f
+File: lispref.info, Node: Example of Receiving Messages, Next: Elisp Interface for Receiving Messages, Up: Receiving Messages
- (setq R (pq-exec P "SELECT * FROM xemacs_test;"))
- => #<PGresult PGRES_TUPLES_OK[5] - SELECT>
+Example of Receiving Messages
+-----------------------------
- 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:
+ 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.
- (pq-exec P "CREATE TABLE a_new_table (i int);")
- => #<PGresult PGRES_COMMAND_OK - CREATE>
+ (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))
- 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:
+\1f
+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.
- (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>
+\1f
+File: lispref.info, Node: LDAP Support, Next: PostgreSQL Support, Prev: ToolTalk Support, Up: Top
- Lastly, when the underlying PGresult object has been deallocated
-directly by `pq-clear' the printed representation will look like:
+LDAP Support
+************
- (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
-
- - 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.
+ XEmacs can be linked with a LDAP client library to provide Elisp
+primitives to access directory servers using the Lightweight Directory
+Access Protocol.
-\1f
-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).
+* Menu:
- `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.
+* 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
\1f
-File: lispref.info, Node: Asynchronous Interface Functions, Next: Large Object Support, Prev: Synchronous Interface Functions, Up: XEmacs PostgreSQL libpq API
+File: lispref.info, Node: Building XEmacs with LDAP support, Next: XEmacs LDAP API, Prev: LDAP Support, Up: LDAP Support
-Asynchronous Interface Functions
---------------------------------
+Building XEmacs with LDAP support
+=================================
- Making command by command examples is too complex with the
-asynchronous interface functions. See the examples section for
-complete calling sequences.
+ 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
- - 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.
+ * OpenLDAP 1.2 (<http://www.openldap.org/>)
- - 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.
+ * University of Michigan's LDAP 3.3
+ (<http://www.umich.edu/~dirsvcs/ldap/>)
- - Function: pq-is-busy conn
- Returns t if `pq-get-result' would block waiting for input. CONN
- A database connection object.
+ * LDAP SDK 1.0 from Netscape Corp. (<http://developer.netscape.com/>)
- - Function: pq-consume-input conn
- Consume any available input from the backend. CONN A database
- connection object.
+ Other libraries conforming to RFC 1823 will probably work also but
+may require some minor tweaking at C level.
- Nil is returned if anything bad happens.
+ 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.
- - Function: pq-reset-start conn
- Reset connection to the backend asynchronously. CONN A database
- connection object.
+\1f
+File: lispref.info, Node: XEmacs LDAP API, Next: Syntax of Search Filters, Prev: Building XEmacs with LDAP support, Up: LDAP Support
- - Function: pq-reset-poll conn
- Poll an asynchronous reset for completion CONN A database
- connection object.
+XEmacs LDAP API
+===============
- - Function: pq-reset-cancel conn
- Attempt to request cancellation of the current operation. CONN A
- database connection object.
+ 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 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.
+ 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).
- - 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)
+* Menu:
- - Function: pq-get-result conn
- Retrieve an asynchronous result from a query. CONN A database
- connection object.
+* 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
- NIL is returned when no more query work remains.
+\1f
+File: lispref.info, Node: LDAP Variables, Next: The High-Level LDAP API, Prev: XEmacs LDAP API, Up: XEmacs LDAP API
- - 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.
+LDAP Variables
+--------------
- - Function: pq-is-nonblocking conn
- Return the blocking status of the database connection CONN A
- database connection object.
+ - 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: pq-flush conn
- Force the write buffer to be written (or at least try) CONN A
- database connection object.
+\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.
+
+ - 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.
- - Function: PQsetenvStart conn
- Start asynchronously passing environment variables to a backend.
- CONN A database connection object.
+\1f
+File: lispref.info, Node: The Low-Level LDAP API, Next: LDAP Internationalization, Prev: The High-Level LDAP API, Up: XEmacs LDAP API
- Compatibility note: this function is only available with libpq-7.0.
+The Low-Level LDAP API
+----------------------
- - Function: PQsetenvPoll conn
- Check an asynchronous enviroment variables transfer for completion.
- CONN A database connection object.
+ 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::
- Compatibility note: this function is only available with libpq-7.0.
+ Note that the former functions `ldap-*-internal' functions have been
+renamed in XEmacs 21.2
- - Function: PQsetenvAbort conn
- Attempt to terminate an asynchronous environment variables
- transfer. CONN A database connection object.
+* Menu:
- Compatibility note: this function is only available with libpq-7.0.
+* The LDAP Lisp Object::
+* Opening and Closing a LDAP Connection::
+* Low-level Operations on a LDAP Server::
\1f
-File: lispref.info, Node: Large Object Support, Next: Other libpq Functions, Prev: Asynchronous Interface Functions, Up: XEmacs PostgreSQL libpq API
+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
-Large Object Support
---------------------
+The LDAP Lisp Object
+....................
- - 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
+ An internal built-in `ldap' lisp object represents a LDAP connection.
- On success, the object id is returned.
+ - Function: ldapp object
+ This function returns non-`nil' if OBJECT is a `ldap' object.
- - 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.
+ - Function: ldap-host ldap
+ Return the server host of the connection represented by LDAP.
-\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.
+ - Function: ldap-live-p ldap
+ Return non-`nil' if LDAP is an active LDAP connection.
\1f
-File: lispref.info, Node: Unimplemented libpq Functions, Prev: Other libpq Functions, Up: XEmacs PostgreSQL libpq API
+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
-Unimplemented libpq Functions
------------------------------
+Opening and Closing a LDAP Connection
+.....................................
- - Unimplemented Function: PGconn *PQsetdbLogin (char *pghost, char
- *pgport, char *pgoptions, char *pgtty, char *dbName, char
- *login, char *pwd)
- Synchronous database connection. PGHOST is the hostname of the
- PostgreSQL backend to connect to. PGPORT is the TCP port number
- to use. PGOPTIONS specifies other backend options. PGTTY
- specifies the debugging tty to use. DBNAME specifies the database
- name to use. LOGIN specifies the database user name. PWD
- specifies the database user's password.
-
- This routine is deprecated as of libpq-7.0, and its functionality
- can be replaced by external Lisp code if needed.
-
- - Unimplemented Function: PGconn *PQsetdb (char *pghost, char *pgport,
- char *pgoptions, char *pgtty, char *dbName)
- Synchronous database connection. PGHOST is the hostname of the
- PostgreSQL backend to connect to. PGPORT is the TCP port number
- to use. PGOPTIONS specifies other backend options. PGTTY
- specifies the debugging tty to use. DBNAME specifies the database
- name to use.
-
- This routine was deprecated in libpq-6.5.
-
- - Unimplemented Function: int PQsocket (PGconn *conn)
- Return socket file descriptor to a backend database process. CONN
- database connection object.
-
- - Unimplemented Function: void PQprint (FILE *fout, PGresult *res,
- PGprintOpt *ps)
- Print out the results of a query to a designated C stream. FOUT C
- stream to print to RES the query result object to print PS the
- print options structure.
-
- This routine is deprecated as of libpq-7.0 and cannot be sensibly
- exported to XEmacs Lisp.
-
- - Unimplemented Function: void PQdisplayTuples (PGresult *res, FILE
- *fp, int fillAlign, char *fieldSep, int printHeader, int
- quiet)
- RES query result object to print FP C stream to print to FILLALIGN
- pad the fields with spaces FIELDSEP field separator PRINTHEADER
- display headers? QUIET
-
- This routine was deprecated in libpq-6.5.
-
- - Unimplemented Function: void PQprintTuples (PGresult *res, FILE
- *fout, int printAttName, int terseOutput, int width)
- RES query result object to print FOUT C stream to print to
- PRINTATTNAME print attribute names TERSEOUTPUT delimiter bars
- WIDTH width of column, if 0, use variable width
-
- This routine was deprecated in libpq-6.5.
-
- - Unimplemented Function: int PQmblen (char *s, int encoding)
- Determine length of a multibyte encoded char at `*s'. S encoded
- string ENCODING type of encoding
-
- Compatibility note: This function was introduced in libpq-7.0.
-
- - Unimplemented Function: void PQtrace (PGconn *conn, FILE *debug_port)
- Enable tracing on `debug_port'. CONN database connection object.
- DEBUG_PORT C output stream to use.
-
- - Unimplemented Function: void PQuntrace (PGconn *conn)
- Disable tracing. CONN database connection object.
-
- - Unimplemented Function: char *PQoidStatus (PGconn *conn)
- Return the object id as a string of the last tuple inserted. CONN
- database connection object.
-
- Compatibility note: This function is deprecated in libpq-7.0,
- however it is used internally by the XEmacs binding code when
- linked against versions prior to 7.0.
-
- - Unimplemented Function: PGresult *PQfn (PGconn *conn, int fnid, int
- *result_buf, int *result_len, int result_is_int, PQArgBlock
- *args, int nargs)
- "Fast path" interface -- not really recommended for application use
- CONN A database connection object. FNID RESULT_BUF RESULT_LEN
- RESULT_IS_INT ARGS NARGS
-
- The following set of very low level large object functions aren't
-appropriate to be exported to Lisp.
-
- - Unimplemented Function: int pq-lo-open (PGconn *conn, int lobjid,
- int mode)
- CONN a database connection object. LOBJID a large object ID.
- MODE opening modes.
-
- - Unimplemented Function: int pq-lo-close (PGconn *conn, int fd)
- CONN a database connection object. FD a large object file
- descriptor
-
- - Unimplemented Function: int pq-lo-read (PGconn *conn, int fd, char
- *buf, int len)
- CONN a database connection object. FD a large object file
- descriptor. BUF buffer to read into. LEN size of buffer.
-
- - Unimplemented Function: int pq-lo-write (PGconn *conn, int fd, char
- *buf, size_t len)
- CONN a database connection object. FD a large object file
- descriptor. BUF buffer to write from. LEN size of buffer.
-
- - Unimplemented Function: int pq-lo-lseek (PGconn *conn, int fd, int
- offset, int whence)
- CONN a database connection object. FD a large object file
- descriptor. OFFSET WHENCE
+ - 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
- - Unimplemented Function: int pq-lo-creat (PGconn *conn, int mode)
- CONN a database connection object. MODE opening modes.
-
- - Unimplemented Function: int pq-lo-tell (PGconn *conn, int fd)
- CONN a database connection object. FD a large object file
- descriptor.
-
- - Unimplemented Function: int pq-lo-unlink (PGconn *conn, int lobjid)
- CONN a database connection object. LBOJID a large object ID.
+ `auth'
+ The authentication method to use, possible values depend on
+ the LDAP library XEmacs was compiled with, they may include
+ `simple', `krbv41' and `krbv42'.
-\1f
-File: lispref.info, Node: XEmacs PostgreSQL libpq Examples, Prev: XEmacs PostgreSQL libpq API, Up: PostgreSQL Support
-
-XEmacs PostgreSQL libpq Examples
-================================
-
- This is an example of one method of establishing an asynchronous
-connection.
-
- (defun database-poller (P)
- (message "%S before poll" (pq-pgconn P 'pq::status))
- (pq-connect-poll P)
- (message "%S after poll" (pq-pgconn P 'pq::status))
- (if (eq (pq-pgconn P 'pq::status) 'pg::connection-ok)
- (message "Done!")
- (add-timeout .1 'database-poller P)))
- => database-poller
- (progn
- (setq P (pq-connect-start ""))
- (add-timeout .1 'database-poller P))
- => pg::connection-started before poll
- => pg::connection-made after poll
- => pg::connection-made before poll
- => pg::connection-awaiting-response after poll
- => pg::connection-awaiting-response before poll
- => pg::connection-auth-ok after poll
- => pg::connection-auth-ok before poll
- => pg::connection-setenv after poll
- => pg::connection-setenv before poll
- => pg::connection-ok after poll
- => Done!
- P
- => #<PGconn localhost:25432 steve/steve>
-
- Here is an example of one method of doing an asynchronous reset.
-
- (defun database-poller (P)
- (let (PS)
- (message "%S before poll" (pq-pgconn P 'pq::status))
- (setq PS (pq-reset-poll P))
- (message "%S after poll [%S]" (pq-pgconn P 'pq::status) PS)
- (if (eq (pq-pgconn P 'pq::status) 'pg::connection-ok)
- (message "Done!")
- (add-timeout .1 'database-poller P))))
- => database-poller
- (progn
- (pq-reset-start P)
- (add-timeout .1 'database-poller P))
- => pg::connection-started before poll
- => pg::connection-made after poll [pgres::polling-writing]
- => pg::connection-made before poll
- => pg::connection-awaiting-response after poll [pgres::polling-reading]
- => pg::connection-awaiting-response before poll
- => pg::connection-setenv after poll [pgres::polling-reading]
- => pg::connection-setenv before poll
- => pg::connection-ok after poll [pgres::polling-ok]
- => Done!
- P
- => #<PGconn localhost:25432 steve/steve>
-
- And finally, an asynchronous query.
-
- (defun database-poller (P)
- (let (R)
- (pq-consume-input P)
- (if (pq-is-busy P)
- (add-timeout .1 'database-poller P)
- (setq R (pq-get-result P))
- (if R
- (progn
- (push R result-list)
- (add-timeout .1 'database-poller P))))))
- => database-poller
- (when (pq-send-query P "SELECT * FROM xemacs_test;")
- (setq result-list nil)
- (add-timeout .1 'database-poller P))
- => 885
- ;; wait a moment
- result-list
- => (#<PGresult PGRES_TUPLES_OK - SELECT>)
-
- Here is an example showing how multiple SQL statements in a single
-query can have all their results collected.
- ;; Using the same `database-poller' function from the previous example
- (when (pq-send-query P "SELECT * FROM xemacs_test;
- SELECT * FROM pg_database;
- SELECT * FROM pg_user;")
- (setq result-list nil)
- (add-timeout .1 'database-poller P))
- => 1782
- ;; wait a moment
- result-list
- => (#<PGresult PGRES_TUPLES_OK - SELECT> #<PGresult PGRES_TUPLES_OK - SELECT> #<PGresult PGRES_TUPLES_OK - SELECT>)
-
- Here is an example which illustrates collecting all data from a
-query, including the field names.
-
- (defun pg-util-query-results (results)
- "Retrieve results of last SQL query into a list structure."
- (let ((i (1- (pq-ntuples R)))
- j l1 l2)
- (while (>= i 0)
- (setq j (1- (pq-nfields R)))
- (setq l2 nil)
- (while (>= j 0)
- (push (pq-get-value R i j) l2)
- (decf j))
- (push l2 l1)
- (decf i))
- (setq j (1- (pq-nfields R)))
- (setq l2 nil)
- (while (>= j 0)
- (push (pq-fname R j) l2)
- (decf j))
- (push l2 l1)
- l1))
- => pg-util-query-results
- (setq R (pq-exec P "SELECT * FROM xemacs_test ORDER BY field2 DESC;"))
- => #<PGresult PGRES_TUPLES_OK - SELECT>
- (pg-util-query-results R)
- => (("f1" "field2") ("a" "97") ("b" "97") ("stuff" "42") ("a string" "12") ("foo" "10") ("string" "2") ("text" "1"))
-
- Here is an example of a query that uses a database cursor.
-
- (let (data R)
- (setq R (pq-exec P "BEGIN;"))
- (setq R (pq-exec P "DECLARE k_cursor CURSOR FOR SELECT * FROM xemacs_test ORDER BY f1 DESC;"))
-
- (setq R (pq-exec P "FETCH k_cursor;"))
- (while (eq (pq-ntuples R) 1)
- (push (list (pq-get-value R 0 0) (pq-get-value R 0 1)) data)
- (setq R (pq-exec P "FETCH k_cursor;")))
- (setq R (pq-exec P "END;"))
- data)
- => (("a" "97") ("a string" "12") ("b" "97") ("foo" "10") ("string" "2") ("stuff" "42") ("text" "1"))
-
- Here's another example of cursors, this time with a Lisp macro to
-implement a mapping function over a table.
-
- (defmacro map-db (P table condition callout)
- `(let (R)
- (pq-exec ,P "BEGIN;")
- (pq-exec ,P (concat "DECLARE k_cursor CURSOR FOR SELECT * FROM "
- ,table
- " "
- ,condition
- " ORDER BY f1 DESC;"))
- (setq R (pq-exec P "FETCH k_cursor;"))
- (while (eq (pq-ntuples R) 1)
- (,callout (pq-get-value R 0 0) (pq-get-value R 0 1))
- (setq R (pq-exec P "FETCH k_cursor;")))
- (pq-exec P "END;")))
- => map-db
- (defun callback (arg1 arg2)
- (message "arg1 = %s, arg2 = %s" arg1 arg2))
- => callback
- (map-db P "xemacs_test" "WHERE field2 > 10" callback)
- => arg1 = stuff, arg2 = 42
- => arg1 = b, arg2 = 97
- => arg1 = a string, arg2 = 12
- => arg1 = a, arg2 = 97
- => #<PGresult PGRES_COMMAND_OK - COMMIT>
+ `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.
-\1f
-File: lispref.info, Node: Internationalization, Next: MULE, Prev: PostgreSQL Support, Up: Top
+ `passwd'
+ The password to use for authentication.
-Internationalization
-********************
+ `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.
-* Menu:
+ `always'
+ Aliases are always dereferenced.
-* I18N Levels 1 and 2:: Support for different time, date, and currency formats.
-* I18N Level 3:: Support for localized messages.
-* I18N Level 4:: Support for Asian languages.
+ `search'
+ Aliases are dereferenced when searching.
-\1f
-File: lispref.info, Node: I18N Levels 1 and 2, Next: I18N Level 3, Up: Internationalization
+ `find'
+ Aliases are dereferenced when locating the base object
+ for the search. The default is `never'.
-I18N Levels 1 and 2
-===================
+ `timelimit'
+ The timeout limit for the connection in seconds.
- XEmacs is now compliant with I18N levels 1 and 2. Specifically,
-this means that it is 8-bit clean and correctly handles time and date
-functions. XEmacs will correctly display the entire ISO-Latin 1
-character set.
+ `sizelimit'
+ The maximum number of matches to return for searches
+ performed on this connection.
- The compose key may now be used to create any character in the
-ISO-Latin 1 character set not directly available via the keyboard.. In
-order for the compose key to work it is necessary to load the file
-`x-compose.el'. At any time while composing a character, `C-h' will
-display all valid completions and the character which would be produced.
+ - Function: ldap-close ldap
+ Close the connection represented by LDAP.
\1f
-File: lispref.info, Node: I18N Level 3, Next: I18N Level 4, Prev: I18N Levels 1 and 2, Up: Internationalization
+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.
-I18N Level 3
-============
+\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:
-* Level 3 Basics::
-* Level 3 Primitives::
-* Dynamic Messaging::
-* Domain Specification::
-* Documentation String Extraction::
+* LDAP Internationalization Variables::
+* Encoder/Decoder Functions::
\1f
-File: lispref.info, Node: Level 3 Basics, Next: Level 3 Primitives, Up: I18N Level 3
+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.
-Level 3 Basics
---------------
+\1f
+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.
- XEmacs now provides alpha-level functionality for I18N Level 3.
-This means that everything necessary for full messaging is available,
-but not every file has been converted.
+ - Function: ldap-encode-string str
+ Encode a string STR according to LDAP-CODING-SYSTEM.
- The two message files which have been created are `src/emacs.po' and
-`lisp/packages/mh-e.po'. Both files need to be converted using
-`msgfmt', and the resulting `.mo' files placed in some locale's
-`LC_MESSAGES' directory. The test "translations" in these files are
-the original messages prefixed by `TRNSLT_'.
+ - 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.
- The domain for a variable is stored on the variable's property list
-under the property name VARIABLE-DOMAIN. The function
-`documentation-property' uses this information when translating a
-variable's documentation.
+ - 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: Level 3 Primitives, Next: Dynamic Messaging, Prev: Level 3 Basics, Up: I18N Level 3
+File: lispref.info, Node: Syntax of Search Filters, Prev: XEmacs LDAP API, Up: LDAP Support
-Level 3 Primitives
-------------------
+Syntax of Search Filters
+========================
- - Function: gettext string
- This function looks up STRING in the default message domain and
- returns its translation. If `I18N3' was not enabled when XEmacs
- was compiled, it just returns STRING.
+ LDAP search functions use RFC1558 syntax to describe the search
+filter. In that syntax simple filters have the form:
- - Function: dgettext domain string
- This function looks up STRING in the specified message domain and
- returns its translation. If `I18N3' was not enabled when XEmacs
- was compiled, it just returns STRING.
+ (<attr> <filtertype> <value>)
- - Function: bind-text-domain domain pathname
- This function associates a pathname with a message domain. Here's
- how the path to message file is constructed under SunOS 5.x:
+ `<attr>' is an attribute name such as `cn' for Common Name, `o' for
+Organization, etc...
- `{pathname}/{LANG}/LC_MESSAGES/{domain}.mo'
+ `<value>' is the corresponding value. This is generally an exact
+string but may also contain `*' characters as wildcards
- If `I18N3' was not enabled when XEmacs was compiled, this function
- does nothing.
+ `filtertype' is one `=' `~=', `<=', `>=' which respectively describe
+equality, approximate equality, inferiority and superiority.
- - Special Form: domain string
- This function specifies the text domain used for translating
- documentation strings and interactive prompts of a function. For
- example, write:
+ Thus `(cn=John Smith)' matches all records having a canonical name
+equal to John Smith.
- (defun foo (arg) "Doc string" (domain "emacs-foo") ...)
+ 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.
- to specify `emacs-foo' as the text domain of the function `foo'.
- The "call" to `domain' is actually a declaration rather than a
- function; when actually called, `domain' just returns `nil'.
+ Simple filters can be connected together with the logical operators
+`&', `|' and `!' which stand for the usual and, or and not operators.
- - Function: domain-of function
- This function returns the text domain of FUNCTION; it returns
- `nil' if it is the default domain. If `I18N3' was not enabled
- when XEmacs was compiled, it always returns `nil'.
+ `(&(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: Dynamic Messaging, Next: Domain Specification, Prev: Level 3 Primitives, Up: I18N Level 3
+File: lispref.info, Node: PostgreSQL Support, Next: Internationalization, Prev: LDAP Support, Up: Top
-Dynamic Messaging
------------------
+PostgreSQL Support
+******************
- The `format' function has been extended to permit you to change the
-order of parameter insertion. For example, the conversion format
-`%1$s' inserts parameter one as a string, while `%2$s' inserts
-parameter two. This is useful when creating translations which require
-you to change the word order.
+ XEmacs can be linked with PostgreSQL libpq run-time support to
+provide relational database access from Emacs Lisp code.
+
+* Menu:
+
+* Building XEmacs with PostgreSQL support::
+* XEmacs PostgreSQL libpq API::
+* XEmacs PostgreSQL libpq Examples::
\1f
-File: lispref.info, Node: Domain Specification, Next: Documentation String Extraction, Prev: Dynamic Messaging, Up: I18N Level 3
+File: lispref.info, Node: Building XEmacs with PostgreSQL support, Next: XEmacs PostgreSQL libpq API, Up: PostgreSQL Support
-Domain Specification
---------------------
+Building XEmacs with PostgreSQL support
+=======================================
- The default message domain of XEmacs is `emacs'. For add-on
-packages, it is best to use a different domain. For example, let us
-say we want to convert the "gorilla" package to use the domain
-`emacs-gorilla'. To translate the message "What gorilla?", use
-`dgettext' as follows:
+ 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.
- (dgettext "emacs-gorilla" "What gorilla?")
+ 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.
- A function (or macro) which has a documentation string or an
-interactive prompt needs to be associated with the domain in order for
-the documentation or prompt to be translated. This is done with the
-`domain' special form as follows:
+ 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'.
- (defun scratch (location)
- "Scratch the specified location."
- (domain "emacs-gorilla")
- (interactive "sScratch: ")
- ... )
+ 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.
- It is most efficient to specify the domain in the first line of the
-function body, before the `interactive' form.
+\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
+===========================
- For variables and constants which have documentation strings,
-specify the domain after the documentation.
+ 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.
- - Special Form: defvar symbol [value [doc-string [domain]]]
- Example:
- (defvar weight 250 "Weight of gorilla, in pounds." "emacs-gorilla")
+ This documentation assumes that the reader has knowledge of SQL, but
+requires no prior knowledge of libpq.
- - Special Form: defconst symbol [value [doc-string [domain]]]
- Example:
- (defconst limbs 4 "Number of limbs" "emacs-gorilla")
+ 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.
- Autoloaded functions which are specified in `loaddefs.el' do not need
-to have a domain specification, because their documentation strings are
-extracted into the main message base. However, for autoloaded functions
-which are specified in a separate package, use following syntax:
+ (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:
- - Function: autoload symbol filename &optional docstring interactive
- macro domain
- Example:
- (autoload 'explore "jungle" "Explore the jungle." nil nil "emacs-gorilla")
+* 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: Documentation String Extraction, Prev: Domain Specification, Up: I18N Level 3
+File: lispref.info, Node: libpq Lisp Variables, Next: libpq Lisp Symbols and DataTypes, Prev: XEmacs PostgreSQL libpq API, Up: XEmacs PostgreSQL libpq API
-Documentation String Extraction
--------------------------------
+libpq Lisp Variables
+--------------------
- The utility `etc/make-po' scans the file `DOC' to extract
-documentation strings and creates a message file `doc.po'. This file
-may then be inserted within `emacs.po'.
+ 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.
- Currently, `make-po' is hard-coded to read from `DOC' and write to
-`doc.po'. In order to extract documentation strings from an add-on
-package, first run `make-docfile' on the package to produce the `DOC'
-file. Then run `make-po -p' with the `-p' argument to indicate that we
-are extracting documentation for an add-on package.
+ - Variable: pg:host
+ Initialized from the PGHOST environment variable. The default
+ host to connect to.
- (The `-p' argument is a kludge to make up for a subtle difference
-between pre-loaded documentation and add-on documentation: For add-on
-packages, the final carriage returns in the strings produced by
-`make-docfile' must be ignored.)
+ - Variable: pg:user
+ Initialized from the PGUSER environment variable. The default
+ database user name.
-\1f
-File: lispref.info, Node: I18N Level 4, Prev: I18N Level 3, Up: Internationalization
+ - Variable: pg:options
+ Initialized from the PGOPTIONS environment variable. Default
+ additional server options.
-I18N Level 4
-============
+ - Variable: pg:port
+ Initialized from the PGPORT environment variable. The default TCP
+ port to connect to.
- The Asian-language support in XEmacs is called "MULE". *Note MULE::.
+ - Variable: pg:tty
+ Initialized from the PGTTY environment variable. The default
+ debugging TTY.
-\1f
-File: lispref.info, Node: MULE, Next: Tips, Prev: Internationalization, Up: Top
+ Compatibility note: Debugging TTYs are turned off in the XEmacs
+ Lisp binding.
-MULE
-****
+ - Variable: pg:database
+ Initialized from the PGDATABASE environment variable. The default
+ database to connect to.
- "MULE" is the name originally given to the version of GNU Emacs
-extended for multi-lingual (and in particular Asian-language) support.
-"MULE" is short for "MUlti-Lingual Emacs". It is an extension and
-complete rewrite of Nemacs ("Nihon Emacs" where "Nihon" is the Japanese
-word for "Japan"), which only provided support for Japanese. XEmacs
-refers to its multi-lingual support as "MULE support" since it is based
-on "MULE".
+ - Variable: pg:realm
+ Initialized from the PGREALM environment variable. The default
+ Kerberos realm.
-* Menu:
+ - 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.
-* Internationalization Terminology::
- Definition of various internationalization terms.
-* Charsets:: Sets of related characters.
-* MULE Characters:: Working with characters in XEmacs/MULE.
-* Composite Characters:: Making new characters by overstriking other ones.
-* Coding Systems:: Ways of representing a string of chars using integers.
-* CCL:: A special language for writing fast converters.
-* Category Tables:: Subdividing charsets into groups.
+ Compatibility Note: This variable is not present in InfoDock.
projects / chise / xemacs-chise.git / blobdiff