.TH SLAPO-RETCODE5 "RELEASEDATE" "OpenLDAP LDVERSION"
-.\" Copyright 1998-2004 The OpenLDAP Foundation, All Rights Reserved.
+.\" Copyright 1998-2006 The OpenLDAP Foundation, All Rights Reserved.
.\" Copying restrictions apply. See the COPYRIGHT file.
.\" Copyright 2001, Pierangelo Masarati, All rights reserved. <ando@sys-net.it>
.\" $OpenLDAP$
In the first case, all operations targeted at a specific configurable
subtree cause the object related to the request DN to be looked up
and checked for return code data: a response code, plus an optional
-textual message, an optional configurable delay, and, when the response code
-is referral, a (list of) referral(s).
+textual message, an optional configurable delay, an optional matched DN
+field, and, when the response code is "referral", a (list of) referral(s).
.LP
Well-known response codes from standard track documents are provided
in \fBretcode.conf\fP, which can be included after instantiating
the overlay.
.LP
-In the second case, objects of \fBerrObject\fP or \fBerrAuxObject\fP class,
-when returned as intermediate responses of a search request, are changed into
-the response dictated by their content.
+In the second case, objects of classes inherited from
+the \fBerrAbsObject\fP, like \fBerrObject\fP or \fBerrAuxObject\fP,
+when returned as intermediate responses of a search request, are changed
+into the response dictated by their content.
.LP
A third mode causes objects to be looked up from the underlying database
-to discover if their class is \fBerrObject\fPor \fBerrAuxObject\fP;
+to discover if their class inherits from \fBerrABsObject\fP;
in that case, their content is used to compute the corresponding response.
.LP
The behavior is disabled by using the \fBmanageDSAit\fP control (RFC 3296);
.HP
.hy 0
.B retcode\-item <RDN> <errCode> [op=<oplist>] [text=<message>]
-.B [ref=<referral>] [sleeptime=<sec>]
+.B [ref=<referral>] [sleeptime=<sec>] [matched=<DN>]
.RS
A dynamically generated entry, located below \fBretcode\-parent\fP.
The \fB<errCode>\fP is the number of the response code;
it can be in any format supported by strtol.
The optional \fB<oplist>\fP is a list of operations that cause
response code generation; if absent, all operations are affected.
+The \fBmatched\fP field is the matched DN that is returned
+along with the error.
The \fBref\fP field is only allowed for the \fBreferral\fP
response code.
.RE
.TP
.B retcode\-indir
-Enables exploitation of in-directory stored errObject/errAuxObject.
+Enables exploitation of in-directory stored errAbsObject.
May result in a lot of unnecessary overhead.
+.TP
+.B retcode\-sleep [-]<n>
+Defines a sleep time in seconds that is spent before actually handling
+any operation.
+If negative, a random time between 0 and the absolute value of the argument
+is used.
.SH SCHEMA
-The following schema items are created and used by the overlay:
+The
+.B retcode
+overlay utilizes the "return code" schema described herein.
+This schema is specifically designed for use with this
+overlay and is not intended to be used otherwise.
+It is also noted that the schema describe here is
+.I a work in
+.IR progress ,
+and hence subject to change without notice.
+The schema is loaded automatically by the overlay.
+
+The schema includes a number of object classes and associated
+attribute types as described below.
+
.LP
The error code:
.RS 4
SINGLE-VALUE )
.RE
.LP
+The matched DN returned to the client:
+.RS 4
+( 1.3.6.1.4.1.4203.666.11.4.1.5
+ NAME ( 'errMatchedDN' )
+ DESC 'Value to be returned as matched DN'
+ EQUALITY distinguishedNameMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
+ SINGLE-VALUE )
+.RE
+.LP
+The abstract class that triggers the overlay:
+.RS 4
+( 1.3.6.1.4.1.4203.666.11.4.3.0
+ NAME ( 'errAbsObject' )
+ SUP top ABSTRACT
+ MUST ( errCode )
+ MAY ( cn $ description $ errOp $ errText $ errSleepTime
+ $ errMatchedDN ) )
+.RE
+.LP
The standalone structural objectclass for specifically created data:
.RS 4
( 1.3.6.1.4.1.4203.666.11.4.3.1
NAME ( 'errObject' )
- SUP top STRUCTURAL
- MUST ( errCode )
- MAY ( cn $ description $ errOp $ errText $ errSleepTime ) )
+ SUP errAbsObject STRUCTURAL )
.RE
.LP
The auxiliary objectclass to alter the behavior of existing objects:
.RS 4
( 1.3.6.1.4.1.4203.666.11.4.3.2
NAME ( 'errAuxObject' )
- SUP top AUXILIARY
- MUST ( errCode )
- MAY ( cn $ description $ errOp $ errText $ errSleepTime ) )
+ SUP errAbsObject AUXILIARY )
.RE
.SH EXAMPLE
.SH SEE ALSO
.BR slapd.conf (5),
.BR slapd (8),
-.SH AUTHOR
-Pierangelo Masarati
+.SH ACKNOWLEDGEMENTS
+.P
+This module was written in 2005 by Pierangelo Masarati for SysNet s.n.c.