X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fman%2Fman5%2Fslapd-sql.5;h=b53811fc2e32b6cb4f9e2a9d554d762ee801db4d;hb=e1a5177baca44d6ff5dceea3f6f91da329d43b85;hp=924acae12ab14ea5de2e6c87617d14c03325a73b;hpb=94747a848929721e44ca110257c90e165936c876;p=openldap

diff --git a/doc/man/man5/slapd-sql.5 b/doc/man/man5/slapd-sql.5
index 924acae12a..b53811fc2e 100644
--- a/doc/man/man5/slapd-sql.5
+++ b/doc/man/man5/slapd-sql.5
@@ -1,7 +1,7 @@
 .TH SLAPD-SQL 5 "RELEASEDATE" "OpenLDAP LDVERSION"
 .\" $OpenLDAP$
 .SH NAME
-slapd-sql \- SQL backend to slapd
+slapd\-sql \- SQL backend to slapd
 .SH SYNOPSIS
 ETCDIR/slapd.conf
 .SH DESCRIPTION
@@ -23,10 +23,10 @@ of BerkeleyDB (as the standard BDB backend does), though it can be
 used as such with several limitations.
 You can take a look at
 .B http://www.openldap.org/faq/index.cgi?file=378 
-(OpenLDAP FAQ-O-Matic/General LDAP FAQ/Directories vs. conventional
+(OpenLDAP FAQ\-O\-Matic/General LDAP FAQ/Directories vs. conventional
 databases) to find out more on this point.
 .LP
-The idea (detailed below) is to use some metainformation to translate
+The idea (detailed below) is to use some meta-information to translate
 LDAP queries to SQL queries, leaving relational schema untouched, so
 that old applications can continue using it without any
 modifications.
@@ -34,7 +34,7 @@ This allows SQL and LDAP applications to inter-operate without
 replication, and exchange data as needed.
 .LP
 The SQL backend is designed to be tunable to virtually any relational
-schema without having to change source (through that metainformation
+schema without having to change source (through that meta-information
 mentioned).
 Also, it uses ODBC to connect to RDBMSes, and is highly configurable
 for SQL dialects RDBMSes may use, so it may be used for integration
@@ -100,17 +100,17 @@ see \fBupper_func\fP, \fBupper_needs_cast\fP, \fBconcat_pattern\fP
 and \fBstrcast_func\fP in "HELPER CONFIGURATION" for details.
 
 .TP
-.B use_subtree_shortcut { NO | yes }
+.B use_subtree_shortcut { YES | no }
 Do not use the subtree condition when the searchBase is the database
 suffix, and the scope is subtree; rather collect all entries.
 
 .RE
-.SH STAMEMENT CONFIGURATION
+.SH STATEMENT CONFIGURATION
 These options specify SQL query templates for loading schema mapping
-metainformation, adding and deleting entries to ldap_entries, etc.
+meta-information, adding and deleting entries to ldap_entries, etc.
 All these and subtree_cond should have the given default values.
 For the current value it is recommended to look at the sources,
-or in the log output when slapd starts with "-d 5" or greater.
+or in the log output when slapd starts with "\-d 5" or greater.
 Note that the parameter number and order must not be changed.
 
 .TP
@@ -161,7 +161,7 @@ The default is
 The statement that is used to delete an existing entry's ID
 from table \fIldap_objclasses\fP; see "METAINFORMATION USED" for details.
 The default is
-\fB""DELETE FROM ldap_entry_objclasses WHERE entry_id=?"\fP.
+\fB"DELETE FROM ldap_entry_objclasses WHERE entry_id=?"\fP.
 
 .RE
 .SH HELPER CONFIGURATION
@@ -250,7 +250,7 @@ or double quotes.
 .B has_ldapinfo_dn_ru { NO | yes }
 Explicitly inform the backend whether the dn_ru column
 (DN in reverse uppercased form) is present in table \fIldap_entries\fP.
-Overrides automatic check (this is required, ofr instance,
+Overrides automatic check (this is required, for instance,
 by PostgreSQL/unixODBC).
 This is \fIexperimental\fP and may change in future releases.
 
@@ -336,11 +336,15 @@ Subsequent args are passed to the layer configuration routine.
 This is \fIhighly experimental\fP and should be used with extreme care.
 The API of the layers is not frozen yet, so it is unpublished.
 
+.TP
+.B autocommit { NO | yes }
+Activates autocommit; by default, it is off.
+
 .SH METAINFORMATION USED
 .LP
 Almost everything mentioned later is illustrated in examples located
 in the
-.B servers/slapd/back-sql/rdbms_depend/
+.B servers/slapd/back\-sql/rdbms_depend/
 directory in the OpenLDAP source tree, and contains scripts for
 generating sample database for Oracle, MS SQL Server, mySQL and more
 (including PostgreSQL and IBM db2).
@@ -520,7 +524,7 @@ not very narrow ;) If anyone needs support for different types for
 keys - he may want to write a patch, and submit it to OpenLDAP ITS,
 then I'll include it.
 .LP
-Also, several people complained that they don't really need very
+Also, several users complained that they don't really need very
 structured trees, and they don't want to update one more table every
 time they add or delete an instance in the relational schema.
 Those people can use a view instead of a real table for ldap_entries, something
@@ -551,8 +555,8 @@ and the baseObject cannot be created; in this case, see the
 directive for a possible workaround.
 
 .LP
-.SH Typical SQL backend operation
-Having metainformation loaded, the SQL backend uses these tables to
+.SH TYPICAL SQL BACKEND OPERATION
+Having meta-information loaded, the SQL backend uses these tables to
 determine a set of primary keys of candidates (depending on search
 scope and filter).
 It tries to do it for each objectclass registered in ldap_objclasses.
@@ -592,7 +596,7 @@ into the most relaxed SQL condition to filter candidates), and send it to
 the user.
 .LP
 ADD, DELETE, MODIFY and MODRDN operations are also performed on per-attribute
-metainformation (add_proc etc.).
+meta-information (add_proc etc.).
 In those fields one can specify an SQL statement or stored procedure
 call which can add, or delete given values of a given attribute, using
 the given entry keyval (see examples -- mostly PostgreSQL, ORACLE and MSSQL 
@@ -605,17 +609,16 @@ Please see samples to find out what are the parameters passed, and other
 information on this matter - they are self-explanatory for those familiar
 with the concepts expressed above.
 .LP
-.SH Common techniques (referrals, multiclassing etc.)
-First of all, let's remember that among other major differences to the
-complete LDAP data model, the concept above does not directly support
-such things as multiple objectclasses per entry, and referrals.
+.SH COMMON TECHNIQUES
+First of all, let's recall that among other major differences to the
+complete LDAP data model, the above illustrated concept does not directly
+support such features as multiple objectclasses per entry, and referrals.
 Fortunately, they are easy to adopt in this scheme.
-The SQL backend suggests one more table being added to the schema:
+The SQL backend requires that one more table is added to the schema:
 ldap_entry_objectclasses(entry_id,oc_name).
 .LP
-The first contains any number of objectclass names that corresponding
-entries will be found by, in addition to that mentioned in
-mapping.
+That table contains any number of objectclass names that corresponding
+entries will possess, in addition to that mentioned in mapping.
 The SQL backend automatically adds attribute mapping for the "objectclass"
 attribute to each objectclass mapping that loads values from this table.
 So, you may, for instance, have a mapping for inetOrgPerson, and use it
@@ -635,14 +638,14 @@ The use of the naming attribute usually requires to add
 an "extensibleObject" value to ldap_entry_objclasses.
 
 .LP
-.SH Caveats
+.SH CAVEATS
 As previously stated, this backend should not be considered
 a replacement of other data storage backends, but rather a gateway
 to existing RDBMS storages that need to be published in LDAP form.
 .LP
 The \fBhasSubordintes\fP operational attribute is honored by back-sql
 in search results and in compare operations; it is partially honored
-also in filtering.  Owing to design limitations, a (braindead?) filter
+also in filtering.  Owing to design limitations, a (brain-dead?) filter
 of the form
 \fB(!(hasSubordinates=TRUE))\fP
 will give no results instead of returning all the leaf entries, because
@@ -652,20 +655,31 @@ If you need to find all the leaf entries, please use
 instead.
 .LP
 A directoryString value of the form "__First___Last_"
-(where underscores should be replaced by spaces) corresponds
+(where underscores mean spaces, ASCII 0x20 char) corresponds
 to its prettified counterpart "First_Last"; this is not currently
 honored by back-sql if non-prettified data is written via RDBMS;
-when non-prettified data is written thru back-sql, the prettified 
+when non-prettified data is written through back-sql, the prettified 
 values are actually used instead.
+
+.LP
+.SH BUGS
+When the
+.B ldap_entry_objclasses
+table is empty, filters on the 
+.B objectClass
+attribute erroneously result in no candidates.
+A workaround consists in adding at least one row to that table,
+no matter if valid or not.
+
 .LP
 .SH PROXY CACHE OVERLAY
 The proxy cache overlay 
 allows caching of LDAP search requests (queries) in a local database.
 See 
-.BR slapo-pcache (5)
+.BR slapo\-pcache (5)
 for details.
 .SH EXAMPLES
-There are example SQL modules in the slapd/back-sql/rdbms_depend/
+There are example SQL modules in the slapd/back\-sql/rdbms_depend/
 directory in the OpenLDAP source tree.
 .SH ACCESS CONTROL
 The