NCLHELP.HLB  —  Directory Module, DSA  Subordinate Reference, 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.

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  –  CREATE

 Use this directive to create a Subordinate Reference entity
 of the specified name.

 Syntax:

    CREATE DSA SUBORDINATE REFERENCE <name> <argument> <value>

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  –  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.

3  –  DELETE

 Use this directive to delete a Subordinate Reference entity.

 Syntax:

 	DELETE DSA SUBORDINATE REFERENCE <name>

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.

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".

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.

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.

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>
Close Help