for most management directives. - ENABLING An ENABLE directive has been issued and the DSA is making itself available for communication. It is the transition between the OFF and ON states. - ON The DSA has been enabled and is ready for use. The DSA can now communicate with applications and other DSAs. - DISABLING A DISABLE directive has been issued and the DSA is disabling itself from service. It is the transition between the ON and OFF states. - UPDATING The DSA is in the processing of replicating information with another DSA. The DSA is either supplying or consuming naming contexts. Syntax: SHOW DSA STATE 4 UID The UID status attribute contains the unique identifier of a DSA entity. The UID is created and assigned when the DSA entity is created (See the CREATE directive). Use of this attribute is deprecated, and the attribute will be removed in a future version. Syntax: SHOW DSA UID 4 Unique_Value_Count The Unique Value Count status attribute specifies the number of unique attribute values present in the DSA's database. This attribute is set by the DSA. A DSA stores a given attribute value only once, to save space and improve the performance of user requests. Syntax: SHOW DSA UNIQUE VALUE COUNT 3 Subordinate_Reference 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. 4 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 {,...} REMOVE DSA SUBORDINATE REFERENCE {,...} SET DSA SUBORDINATE REFERENCE {,...} SHOW DSA SUBORDINATE REFERENCE where is the characteristic attribute name and 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 , Similarly, you can achieve the same result by using the ALL CHARACTERISTICS qualifier with the SHOW directive. For example: SHOW DSA SUBORDINATE REFERENCE ALL CHARACTERISTICS 5 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 ACCESS POINT {,...} REMOVE DSA SUBORDINATE REFERENCE ACCESS POINT {,...} SET DSA SUBORDINATE REFERENCE ACCESS POINT {,...} SHOW DSA SUBORDINATE REFERENCE ACCESS POINT where is the access point of the DSA and is specified as follows: {[ae title = "", 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. 5 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 COPY ACCESS POINT {,...} REMOVE DSA SUBORDINATE REFERENCE COPY ACCESS POINT {,...} SET DSA SUBORDINATE REFERENCE COPY ACCESS POINT {,...} SHOW DSA SUBORDINATE REFERENCE COPY ACCESS POINT where is the access point of a DSA to which the Subordinate Reference refers, and is specified as follows: [ae title = "", 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. 4 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. 5 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 {,...} where is the name of the Characteristic attribute and is the value you want to add to the attribute. 5 CREATE Use this directive to create a Subordinate Reference entity of the specified name. Syntax: CREATE DSA SUBORDINATE REFERENCE 6 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 where is the access point of the DSA and is specified as follows: {[ae title = "", 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 where is the access point of the DSA and is specified as shown in the preceding description of the ACCESS POINT argument. 6 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. 5 DELETE Use this directive to delete a Subordinate Reference entity. Syntax: DELETE DSA SUBORDINATE REFERENCE 6 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. 5 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 {,...} where is the identifier of a Subordinate Reference entity, is the name of the characteristic attribute and is the value you want to remove from the attribute. 5 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 {,...} where is the name of the Subordinate Reference entity, is the name of the Characteristic attribute and is the value you want to set for the attribute. 5 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 where 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 , You can also use the wildcard "*" in a SHOW directive, to show details of all subordinate references; for example: SHOW DSA SUBORDINATE REFERENCE * 4 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. 3 Superior_Reference A Superior Reference entity provides a reference to a DSA that holds a naming context that is higher in the DIT than all of the naming contexts held locally. The DSA that holds superior information should have further knowledge information that enables the user request to be redirected to the relevant DSA. Such a DSA might have knowledge about parts of the DIT that this DSA does not know about. 4 Characteristics A Superior Reference entity has one characteristic attribute: Access Point. You can use the ADD, SET, SHOW and REMOVE directives on this attribute. Syntax: ADD DSA SUPERIOR REFERENCE ACCESS POINT {} REMOVE DSA SUPERIOR REFERENCE ACCESS POINT {} SET DSA SUPERIOR REFERENCE ACCESS POINT {} SHOW DSA SUPERIOR REFERENCE ACCESS POINT where is the value. The Access Point attribute is single-valued. 5 Access_Point This specifies the Access Point of the DSA which holds a naming context which is superior to all of the naming contexts held within this DSA. There is no default value. The attribute is single-valued. Syntax: ADD DSA SUPERIOR REFERENCE ACCESS POINT {} REMOVE DSA SUPERIOR REFERENCE ACCESS POINT {} SET DSA SUPERIOR REFERENCE ACCESS POINT {} SHOW DSA SUPERIOR REFERENCE ACCESS POINT where is the access point of a DSA that holds a master copy of a naming context that is higher than all naming contexts on this DSA, and is specified as follows: [ae title = "", 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 the DSA in the 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. 4 Directives You can use the CREATE, DELETE, SET and SHOW directives with the Superior Reference entity. The CREATE and DELETE directives are used to create and delete a Superior Reference entity. The SET and SHOW directives are used to set or display the Superior Reference characteristic attribute, respectively. Note that the only characteristic attribute of the Superior Reference entity is single valued. The ADD and REMOVE directives can therefore only be used to remove the single value, or to add a value if there is no existing value. 5 ADD Use the ADD directive to add value to the Access Point attribute if it does not already have one. Syntax: ADD DSA SUPERIOR REFERENCE {} where is the name of the Characteristic attribute and is the value you want to add to the attribute. Note that the Access Point attribute is single-valued, so you can only use the ADD directive if the Access Point currently has no value. 5 CREATE Use this directive to create a Superior Reference entity. Syntax: CREATE DSA SUPERIOR REFERENCE 6 Arguments The CREATE directive has one argument: ACCESS POINT. This argument is optional, although a Superior Reference entity without an Access Point attribute serves no purpose. You can specify the Access Point attribute using the SET directive instead. The ACCESS POINT argument identifies a DSA holding a naming context which is superior to all the naming contexts contained within this DSA. Specify the ACCESS POINT argument in the following format: ACCESS POINT where is the access point of the DSA and is specified as follows: {[ae title = "", 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 the DSA in the 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. 6 Errors The CREATE directive returns one of the following errors: REASON: Already Exists DESCRIPTION: The Superior Reference entity already exists. 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 create a Superior Reference entity. Any other state causes a failure. The response indicates the current state of the DSA. 5 DELETE Use this directive to delete the Superior Reference entity. Syntax: DELETE DSA SUPERIOR REFERENCE 6 Errors The Delete directive returns one error only: 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 Superior Reference entity. Any other state causes a failure. The response indicates the current state of the DSA. 5 Examples > CREATE DSA SUPERIOR REFERENCE - _> ACCESS POINT {[AE Title="/C=US/O=Abacus/CN=DSA5", - _> Pres Addr='"DSA"/"DSA"/"DSA"/NS+49002aaa000400888888']} > SHOW DSA SUPERIOR REFERENCE ALL ATTRIBUTES The first command creates a Superior Reference entity and defines the access point of the DSA which holds a naming context superior to all naming contexts contained within this DSA. Note that the command specifies no identifier for the Superior Reference entity. The second command displays the Superior Reference entity. > DELETE DSA SUPERIOR REFERENCE This command deletes the Superior Reference entity. 5 REMOVE Use the REMOVE directive to remove a value from the Access Point attribute. Syntax: REMOVE DSA SUPERIOR REFERENCE {} where is the name of the Characteristic attribute and is the value of the attribute. Note that the Access Point attribute is single-valued, so there is only ever one value for you to remove. 5 SET Use the SET directive to change the value of the Superior Reference characteristic attribute. Syntax: SET DSA SUPERIOR REFERENCE ACCESS POINT {} where is the value you want to set for the attribute. 5 SHOW Use the SHOW directive to display the characteristic attribute of a Superior Reference entity. Syntax: SHOW DSA SUPERIOR REFERENCE ACCESS POINT