A Subordinate Reference entity provides a reference to a Naming Context entity that is beneath a Naming Context entity held by this DSA. The subordinate Naming Context entity might also be held by this DSA; it is not necessarily on a remote DSA. A subordinate reference enables a DSA to redirect requests for information that it does not hold. It also marks the point at which one naming context ends, and another begins.
1 – Characteristics
Each Subordinate Reference entity has two characteristic attributes:
- Access Point
- Copy Access Point
You can use the ADD, SET, SHOW and REMOVE directives on both these
attributes.
Syntax:
ADD DSA SUBORDINATE REFERENCE <name> <attr> {<value>,...}
REMOVE DSA SUBORDINATE REFERENCE <name> <attr> {<value>,...}
SET DSA SUBORDINATE REFERENCE <name> <attr> {<value>,...}
SHOW DSA SUBORDINATE REFERENCE <name> <attr>
where <attr> is the characteristic attribute name and
<value> is the value.
The Access Point attribute is single-valued.
You can display the value of both attributes in one SHOW
directive by separating the attributes with a comma. For example:
SHOW DSA SUBORDINATE REFERENCE <name> <attribute1>, <attribute2>
Similarly, you can achieve the same result by using the ALL
CHARACTERISTICS qualifier with the SHOW directive. For example:
SHOW DSA SUBORDINATE REFERENCE <name> ALL CHARACTERISTICS
1.1 – Access Point
This specifies the Access Point of the DSA which holds the master
copy of a directory entry subordinate to the current entry. There
is no default value.
Syntax:
ADD DSA SUBORDINATE REFERENCE <name> ACCESS POINT {<value>,...}
REMOVE DSA SUBORDINATE REFERENCE <name> ACCESS POINT {<value>,...}
SET DSA SUBORDINATE REFERENCE <name> ACCESS POINT {<value>,...}
SHOW DSA SUBORDINATE REFERENCE <name> ACCESS POINT
where <value> is the access point of the DSA and is
specified as follows:
{[ae title = "<distinguished name of DSA>",
presentation address = '<presentation address>']}
The AE Title and Presentation Address attributes are both mandatory.
Note that you must specify the AE Title and Presentation
Address in the order shown above.
Specify all valid NSAPs for a DSA in an access point. This
improves the network efficiency of the DSA, ensuring that if
a connection to the relevant DSA already exists, it is always
re-used.
Refer to DSA Common_Datatypes for more information
on how to specify an AE Title and a Presentation Address.
1.2 – Copy Access Point
This specifies the DSA which holds a copy of a directory
entry subordinate to the current entry. There is no default
value.
Syntax:
ADD DSA SUBORDINATE REFERENCE <name> COPY ACCESS POINT {<value>,...}
REMOVE DSA SUBORDINATE REFERENCE <name> COPY ACCESS POINT {<value>,...}
SET DSA SUBORDINATE REFERENCE <name> COPY ACCESS POINT {<value>,...}
SHOW DSA SUBORDINATE REFERENCE <name> COPY ACCESS POINT
where <value> is the access point of a DSA to which the
Subordinate Reference refers, and is specified as follows:
[ae title = "<distinguished name of DSA>",
presentation address = '<presentation address>']
The AE Title and the presentation address are both mandatory.
Note that the order of the AE Title and presentation
address must be the same as that shown above.
Specify all valid NSAPs for a DSA in an access point. This
improves the network efficiency of the DSA, ensuring that if
a connection to the relevant DSA already exists, it is always
re-used.
Refer to DSA Common_Datatypes for more information
on how to specify an AE Title and a Presentation Address.
2 – Directives
You can use the ADD, CREATE, DELETE, REMOVE, SET and SHOW directives with the Subordinate Reference entity. The CREATE and DELETE directives are used to create and delete a Subordinate Reference entity. The SET and SHOW directives are used to set or show Subordinate Reference characteristic attributes, respectively. The ADD and REMOVE directives are used to add or remove values to or from a characteristic attribute.
2.1 – ADD
Use the ADD directive to add value(s) to a characteristic
attribute of the Subordinate Reference entity.
You can use the ADD directive on all characteristic attributes of
the Subordinate Reference entity.
Syntax:
ADD DSA SUBORDINATE REFERENCE <attr> {<value>,...}
where <attr> is the name of the Characteristic
attribute and <value> is the value you want to add to
the attribute.
2.2 – CREATE
Use this directive to create a Subordinate Reference entity
of the specified name.
Syntax:
CREATE DSA SUBORDINATE REFERENCE <name> <argument> <value>
2.2.1 – Arguments
The CREATE directive has an identifier and two arguments:
- ACCESS POINT
- COPY ACCESS POINT
The identifier specifies the name of this
Subordinate Reference entity. This is in the form of a
distinguished name.
The ACCESS POINT argument identifies the DSA holding the master copy
of the naming context for which this entity provides a reference.
The attribute is single-valued. Specify the ACCESS POINT argument
in the following format:
ACCESS POINT <access point>
where <access point> is the access point of the DSA and is
specified as follows:
{[ae title = "<distinguished name of DSA>",
presentation address = '<presentation address>']}
The AE Title and Presentation Address attributes are both mandatory.
Note that you must specify the AE Title and Presentation
Address in the order shown above.
Specify all valid NSAPs for a DSA in an access point. This
improves the network efficiency of the DSA, ensuring that if
a connection to the relevant DSA already exists, it is always
re-used.
Refer to DSA Common_Datatypes for more information
on how to specify an AE Title and a Presentation Address.
The COPY ACCESS POINT is optional and specifies one or more DSAs
that hold a copy of the naming context to which this entity
provides a reference. Specify the COPY ACCESS POINT argument
in the following format:
COPY ACCESS POINT <access point>
where <access point> is the access point of the DSA and is
specified as shown in the preceding description of the
ACCESS POINT argument.
2.2.2 – Errors
The CREATE directive returns one of the following errors:
REASON: Already Exists
DESCRIPTION: This Subordinate Reference entity already exists.
REASON: Invalid Name
DESCRIPTION: The entity name is not a valid directory name.
The name of the entity must be in the form of a
distinguished name. The response shows the
invalid name.
REASON: Not Master
DESCRIPTION: Cannot create a Subordinate Reference in a
shadow Naming Context.
You cannot create a Subordinate Reference entity
within a shadow Naming Context. You must
create a Subordinate Reference entity on the DSA
that is listed as being the master DSA for the
naming context that should contain this reference,
and then replicate the new reference to all
shadow DSAs for that naming context. The response
identifies the master DSA for the naming context.
REASON: Entry Already Exists
DESCRIPTION: The DSA already holds an entry with the specified
name.
If an entry already exists with the name that
you specify, then it would be inappropriate to
create a Subordinate Reference entity of the same
name. The Subordinate Reference entity marks the
termination of a naming context, but the existence
of an entry already in that place indicates
that some naming context extends beyond the
proposed termination point.
REASON: Alias Entry Already Exists
DESCRIPTION: The DSA already holds an alias entry with the
specified name.
An alias entry already exists with the same
name. An alias entry cannot have subordinate
entries, so it is inappropriate to create a
reference downwards from this position in the DIT.
REASON: Naming Context Already Exists
DESCRIPTION: The DSA already holds a Naming Context entity
with the specified name.
A Naming Context entity already exists at this
position in the DIT. A Subordinate Reference
entity cannot be created if a Naming Context
entity already exists at that location. If a
Subordinate Reference entity is really required
at this position, to terminate some higher
naming context, then it must be created before the
creation of the Naming Context entity with which
it might then coexist. To reduce the chances of
invalid configurations, the DSA requires you to
create entities in a logical order, marking the
termination of one context before allowing the
creation of another.
REASON: Has Subordinates
DESCRIPTION: The DSA already holds entries or entities
subordinate to the entity being created.
Subordinate entries exist below the proposed
location of the Subordinate Reference entity.
To create a Subordinate Reference entity in
the proposed position would leave these entries
beyond the termination point of whichever naming
context they are part of.
REASON: Below Subordinate Reference
DESCRIPTION: The directly superior entity is another Subordinate
Reference.
There is already a Subordinate Reference entity
higher up the DIT. You cannot create consecutive
Subordinate Reference entities.
REASON: DIT Root
DESCRIPTION: Cannot create a Subordinate Reference at the root of
the DIT.
You cannot create a Subordinate Reference entity
directly on the root entry of a DIT (/). A
Subordinate Reference entity must have a
distinguished name that contains at least one
relative distinguished name.
REASON: Alias entry
DESCRIPTION: Alias entry prevents creation.
The identifier you specified for the Subordinate
Reference entity is an alias name, not a
distinguished name. The DSA does not support the
use of alias names when creating entities. Specify
the distinguished name of the entry at the top
of the naming context to which this entity
provides a reference. The response shows the name
of the alias entry.
REASON: Wrong State
DESCRIPTION: The DSA entity is not in the correct state.
The DSA must be in state ON, ENABLING, DISABLING
or OFF when you create a Subordinate Reference
entity. The response shows the current state of
the DSA.
2.3 – DELETE
Use this directive to delete a Subordinate Reference entity. Syntax: DELETE DSA SUBORDINATE REFERENCE <name>
2.3.1 – Errors
The Delete directive returns one of the following errors:
REASON: Also a Naming Context
DESCRIPTION: The Naming Context entity of the same name
must be deleted first.
You cannot delete the Subordinate Reference
entity because it coexists with a Naming
Context entity. To delete the Subordinate
Reference entity first would leave the DIT
improperly structured.
REASON: Also a Shadow Naming Context
DESCRIPTION: The shadow Naming Context with the same name
must be removed first.
You cannot delete the Subordinate Reference
entity because it coexists with a shadow
Naming Context entity. You need to reconfigure
the supplier DSA for the shadow naming context
so that this DSA is no longer a consumer DSA for it.
Then initiate replication so that this DSA removes
its copy of the naming context. You can then remove
the Subordinate Reference entity. The response
identifies the name of the shadow naming context
and its master DSA.
REASON: Not Master
DESCRIPTION: Cannot delete a shadow Subordinate Reference.
The Subordinate Reference entity is a shadow
copy that has been created by replication.
The DSA does not own the entity and cannot
therefore delete it. You need to reconfigure
the supplier DSA so that this DSA is no longer
a consumer DSA for the specified naming context.
Then initiate replication so that this DSA removes
its copy of the Naming Context, including
the Subordinate Reference entity. The response
identifies the name of the shadow naming context
and its master DSA.
REASON: Has Subordinates
DESCRIPTION: The DSA holds entries or entities
subordinate to the entity being deleted.
The Subordinate Reference entity has
subordinates and therefore cannot be deleted.
You need to delete all subordinate entries
and entities first.
REASON: Alias Entry
DESCRIPTION: Alias entry prevents deletion.
The identifier you specified for the Subordinate
Reference entity is an alias name, not a
distinguished name. The DSA does not support the
use of alias names when deleting entities. The
response shows the name of the alias entry.
REASON: Wrong State
DESCRIPTION: The DSA entity is not in the correct state.
The DSA entity must be in state ON, ENABLING,
DISABLING or OFF when you delete a
Subordinate Reference entity.
2.4 – Examples
> CREATE DSA SUBORDINATE REFERENCE "/C=US/O=Abacus/OU=Sales" -
_> ACCESS POINT {[AE Title="/C=US/O=Abacus/CN=DSA4", -
_> Pres Addr='"DSA"/"DSA"/"DSA"/NS+49002aaa000400083221']} -
_> COPY ACCESS POINT {[AE Title="/C=US/O=Abacus/CN=DSA6", -
_> Pres Addr='"DSA"/"DSA"/"DSA"/NS+49002aaa000400081222']}
> SHOW DSA SUBORDINATE REFERENCE "/C=US/O=Abacus/OU=Sales" -
_> ALL ATTRIBUTES
The first command creates a Subordinate Reference entity
and defines the access points of the master DSA and a
shadow DSA of the subordinate naming context to which
this entity provides a reference. The second command
displays the Subordinate Reference entity.
> DELETE DSA SUBORDINATE REFERENCE "/C=US/O=Abacus/OU=Sales"
This command deletes the Subordinate Reference entity
with the identifier "/C=US/O=Abacus/OU=Sales".
2.5 – REMOVE
Use the REMOVE directive to remove value(s) from a
characteristic attribute.
You can use the REMOVE directive on all Subordinate
Reference characteristic attributes.
Syntax:
REMOVE DSA SUBORDINATE REFERENCE <name> <attr> {<value>,...}
where <name> is the identifier of a Subordinate Reference entity,
<attr> is the name of the characteristic attribute and <value> is
the value you want to remove from the attribute.
2.6 – SET
Use the SET directive to change the value of a Subordinate
Reference characteristic attribute.
You can use the SET directive on all characteristic attributes
of the Subordinate Reference entity.
Syntax:
SET DSA SUBORDINATE REFERENCE <name> <attr> {<value>,...}
where <name> is the name of the Subordinate Reference entity,
<attr> is the name of the Characteristic attribute and
<value> is the value you want to set for the attribute.
2.7 – SHOW
Use the SHOW directive to display the characteristic attributes of a Subordinate Reference entity. You can use the SHOW directive on all Characteristic attributes of the Subordinate Reference entity. Syntax: SHOW DSA SUBORDINATE REFERENCE <name> <attr> where <attr> is the name of the Characteristic attribute you want to display. You can display the values of multiple attributes using one SHOW directive by separating the attributes with a comma, for example: SHOW DSA SUBORDINATE REFERENCE <name> <attr1>, <attr2> You can also use the wildcard "*" in a SHOW directive, to show details of all subordinate references; for example: SHOW DSA SUBORDINATE REFERENCE * <attr>
3 – Identifier
The identifier of a Subordinate Reference entity is the distinguished name of the entry to which the entity provides a reference, for example, "/C=US/O=Abacus/OU=Accounts". The identifier of a Subordinate Reference entity is the same as the identifier of a Naming Context entity held by some other DSA. Thus the entity provides a reference to the remote naming context. It is possible for the Subordinate Reference entity to be on the same DSA as the Naming Context entity to which it provides a reference. Refer to DSA Common_Datatypes for more information on how to specify a distinguished name. Refer to the CREATE directive for more information on how to create a Subordinate Reference entity.