Manual Object- Related Processes Now that we have reviewed the major background processes, the following sections examine the processes you invoke by using the administrative utilities. The first set of such processes is object-related processes. The following sections examine the creation, renaming, deletion, and movement of objects in the NDS tree. Creating Objects Object creation is a fairly straightforward process. In ConsoleOne, for instance, you select the context where you want the new object to be placed and either click Insert or right-click the container you want to create the object in and then select Create from the menu. ConsoleOne asks you for the object class, and after you select that, you are presented with an appropriate dialog box to enter the mandatory attributes of the object. From the server's perspective, object creation is also a simple process. The client API generates the DSA request verb DSV_ADD_ENTRY (decimal value 7) and submits it to the server. Listing 6.4 shows the DSA Add Entry request for User object PKuo . NOTE You can find a list of DS verbs and their values, along with explanations of their functions, in Appendix B .
Listing 6.4. A DSA Add Entry Request Shown on a Server Processing a Client Request DSA: DSACommonRequest(7) conn:3 for client <JIM> DSA REQUEST BUFFER: 02 00 00 00 00 00 00 00 FF FF FF FF E3 02 00 12 ................ 0A 00 00 00 50 00 4B 00 75 00 6F 00 00 00 00 00 ....P.K.u.o..... 02 00 00 00 10 00 00 00 53 00 75 00 72 00 6E 00 ........S.u.r.n. 61 00 6D 00 65 00 00 00 01 00 00 00 08 00 00 00 a.m.e........... 4B 00 75 00 6F 00 00 00 1A 00 00 00 4F 00 62 00 K.u.o.......O.b. 6A 00 65 00 63 00 74 00 20 00 43 00 6C 00 61 00 j.e.c.t...C.l.a. 73 00 73 00 00 00 00 00 01 00 00 00 0A 00 00 00 s.s............. 55 00 53 00 45 00 52 00 00 00 U.S.E.R...
The request buffer is filled with the information entered in the Create Object dialog box. In the listings in this section, this information is seen on the server processing the client request by enabling the +DSA and +BUFFERS ( +CBUF on Unix) flags in DSTrace. NOTE Offset counting always starts with zero.
The information shown in the request buffer is in Unicode format, which is a 2-byte character format. For English-language objects, Unicode fills the first byte with 00. In Listings 6.4 and 6.5, you can see the object name starting at offset 19, followed by the mandatory attribute Surname (offset 39) and its value (offset 63). Finally, you can see the Object class attribute and the value USER . This is the minimum information needed to create a User object and is passed directly to the DSA from ConsoleOne. If the object already exists, the server's reply is shown right after the request, as shown in Listing 6.5. Listing 6.5. A DSA Add Entry Request with Failure DSA: DSACommonRequest(7) conn:3 for client <JIM> DSA REQUEST BUFFER: 02 00 00 00 00 00 00 00 FF FF FF FF E3 02 00 12 ................ 0A 00 00 00 50 00 4B 00 75 00 6F 00 00 00 00 00 ....P.K.u.o..... 02 00 00 00 10 00 00 00 53 00 75 00 72 00 6E 00 ........S.u.r.n. 61 00 6D 00 65 00 00 00 01 00 00 00 08 00 00 00 a.m.e........... 4B 00 75 00 6F 00 00 00 1A 00 00 00 4F 00 62 00 K.u.o.......O.b. 6A 00 65 00 63 00 74 00 20 00 43 00 6C 00 61 00 j.e.c.t...C.l.a. 73 00 73 00 00 00 00 00 01 00 00 00 0A 00 00 00 s.s............. 55 00 53 00 45 00 52 00 00 00 U.S.E.R... DSA REPLY BUFFER: DSA: DSACommonRequest(7): returning ERROR 606
The error code -606 is defined as ERR_ENTRY_ALREADY_EXISTS . This makes sense because in this example, the object does in fact already exist in the specified context. Object creation can take place on any writable replica. When a create request is completed on the server that the workstation contacts, the object is queued up for the next synchronization cycle and sent out to the other servers in the replica ring. As discussed in the section "The Synchronization Process," this synchronization cycle is either transitive or nontransitive, depending on the version of NetWare and NDS/eDirectory running on the servers in the replica ring. Renaming Objects Renaming an object is a fairly simple process. The request is actually broken into two parts ”a Resolve Name request ( DSV_RESOLVE_NAME , decimal value 1), as shown in Listing 6.6, and the actual Rename operation, as shown in Listing 6.7. This example renames the object PKuo as JimH . This operation requires that the client be able to contact a server holding a writable copy of the object being renamed . Listing 6.6. An Object Resolve Name Request Issued During an Object Renaming Operation DSA: DSACommonRequest(1) conn:3 for client <JIM> DSA REQUEST BUFFER: 00 00 00 00 24 20 00 00 00 00 00 00 30 00 00 00 ............0... 50 00 4B 00 75 00 6F 00 2E 00 4F 00 55 00 3D 00 P.K.u.o...O.U... 45 00 61 00 73 00 74 00 2E 00 4F 00 3D 00 58 00 E.a.s.t...O...X. 59 00 5A 00 43 00 6F 00 72 00 70 00 00 00 00 00 Y.Z.C.o.r.p..... 02 00 00 00 00 00 00 00 08 00 00 00 02 00 00 00 ................ 00 00 00 00 08 00 00 00 ........ DSA REPLY BUFFER: 01 00 00 00 BC 02 00 0E 01 00 00 00 00 00 00 00 ................ 0C 00 00 00 84 12 30 01 00 00 00 00 00 01 04 51 ......0........Q
Listing 6.7. An Object Rename Request DSA: DSACommonRequest(10) conn:3 for client <JIM> DSA REQUEST BUFFER: 00 00 00 00 BC 02 00 0E 01 00 00 00 0A 00 00 00 .............. 4A 00 69 00 6D 00 48 00 00 00 6F 00 J.i.m.H...o. DSA REPLY BUFFER:
The reply sent to the Resolve Name request returns the object ID of the object being renamed, starting at offset 4 in reverse-byte order, as shown in bold in Listing 6.6. In this example, the entry being renamed has an entry ID of 0E0002BC. The server responding also includes its network address in the reply buffer. In this example, the (IPX) address is shown starting at off-set 20. Unlike the entry ID, the address value is not in reverse-byte order, and it includes the network, the node, and the socket address. In this example, the address is 84123001:000000000001:0451. When the requested information is returned, the client sends the Rename request ( DSV_MODIFY_RDN , decimal value 10) to the server that replied to the Read request. The request buffer for the Rename request does not include the old object name; rather, it uses the object's ID, retrieved from the Resolve Name request that occurred at the start of the rename operation. This object ID is again put at offset 4, in reverse-byte order. In Listing 6.7, this is 0E0002BC, shown in bold, the same object ID returned by the Resolve Name request. In a rename operation, the object ID in the Rename request always matches the ID read in the initial Resolve Name request. This is how the client knows which object is being renamed. NOTE When an object is renamed, only its RDN is changed; thus, the verb is DSV_MODIFY_RDN .
In a multiserver environment, the rename operation sets in motion a series of events to ensure that the rename operation is synchronized properly. The old object ID has an OLD_RDN obituary issued for it in order to start processing the purge of the old name from the DS database. At the same time, a NEW_RDN obituary is issued for the new object name. If one of the servers in the replica ring is unavailable, you can see the obituaries that have been issued for the rename operation. By running DSRepair (with the -A command-line parameter), you can view the current obituaries and their states on the server by performing an external reference check. Listing 6.8 shows the information written to the DSREPAIR.LOG file about the two obituaries that have been created by renaming the object PKuo as JimH . Listing 6.8. A DSRepair Log File, Showing Obituaries Created by a Rename Operation /*************************************************************/ Directory Services Repair 10550.61, DS 10550.98 Log file for server ".VEGA.DreamLAN.W2K_EDIR_873." in tree "W2K_EDIR_873" External Reference Check Start: 01/16/2004 10:37:16 PM Local Time (1) Found obituary for: EID: 0e0002bc, DN: CN=JimH.OU=East.O=XYZCorp.T=W2K_EDIR_873 -Value CTS : 01/16/2004 10:36:42 PM R = 0001 E = 0003 -Value MTS = 01/16/2004 10:36:42 PM R = 0001 E = 0003, Type = 0005 NEW_RDN, -Flags = 0000 -RDN: CN=JimH (2) Found obituary for: EID: 0e0002bc, DN: CN=JimH.OU=East.O=XYZCorp.T=W2K_EDIR_873 -Value CTS : 01/16/2004 10:36:42 PM R = 0001 E = 0004 -Value MTS = 01/16/2004 10:36:42 PM R = 0001 E = 0004, Type = 0006 BACKLINK, -Flags = 0000 -Backlink: Type = 00000005 NEW_RDN, RemoteID = ffffffff, ServerID = 000080a3, CN=RIGEL.O=eDir_Book.T=W2K_EDIR_873 Checked 0 external references Found: 2 total obituaries in this dib, 2 Unprocessed obits, 0 Purgeable obits, 0 OK_To_Purge obits, 0 Notified obits *** END ***
From the section "Obituaries," you know that a Backlink obituary was created because the server Rigel contains either a real copy or an exref of the object. The obituaries that are issued do not prevent you from performing other operations on the object. In fact, after an object is renamed, it is possible to create a new object by using the original object's name. TIP Because the OLD_RDN and NEW_RDN obituary types do not hold up other operations, these obituaries can hang around for a very long time and not be detected . Periodically checking the state of obituaries by using DSRepair helps ensure that Flat Cleaner process is properly advancing and purging the obituaries.
Deleting Objects Deleting an object from the tree is similar to renaming an object in the tree. As with the rename operation, the delete operation requires that the client be able to communicate with any server that holds a writable copy of the object. First, a Resolve Name request is sent; it is similar to the one that appears before the rename operation in Listing 6.6. As with the rename object operation, the reply buffer includes both the object ID of the object being deleted and the network address of the server that responded to the request. When this information is returned, the client requests the actual deletion of the object by using DSA verb DSV_REMOVE_ENTRY (decimal value 8). This request is shown in Listing 6.9. Listing 6.9. A DSA Remove Entry Request DSA: DSACommonRequest(8) conn:3 for client <JIM> DSA REQUEST BUFFER: 00 00 00 00 BA 02 00 10 ........ DSA REPLY BUFFER:
You again see the object ID passed into the request starting at offset 4, in reverse-byte order. This request is for object ID 010002BA to be deleted. The object ID requested again corresponds to the object ID returned by the Resolve Name request at offset 4. Object deletion creates an obituary of class Dead . Again, by using DSRepair with the -A switch and checking external references, you can see the obituaries created by deleting the object. Listing 6.10 shows the log file entries that result from this operation. Listing 6.10. A DSRepair Log, Showing Obituaries Created by a Deletion /*************************************************************/ Directory Services Repair 10550.61, DS 10550.98 Log file for server ".BETELGEUSE.DreamLAN.W2K_EDIR_873." in tree "W2K_EDIR_873" External Reference Check Start: 01/16/2004 11:00:50 PM Local Time (1) Found obituary for: EID: 010002ba, DN: CN=JimH.OU=East.O=XYZCorp.T=W2K_EDIR_873 -Value CTS : 01/16/2004 11:00:32 PM R = 0001 E = 0001 -Value MTS = 01/16/2004 11:00:32 PM R = 0001 E = 0001, Type = 0001 DEAD, -Flags = 0000 (2) Found obituary for: EID: 010002ba, DN: CN=JimH.OU=East.O=XYZCorp.T=W2K_EDIR_873 -Value CTS : 01/16/2004 11:00:32 PM R = 0001 E = 0002 -Value MTS = 01/16/2004 11:00:32 PM R = 0001 E = 0002, Type = 0006 BACKLINK, -Flags = 0000 -Backlink: Type = 00000001 DEAD, RemoteID = ffffffff, ServerID = 000080a3, CN=DREAMLAN-W2KB-NDS.O=eDir_Book.T=W2K_EDIR_873 (3) Found obituary for: EID: 010002ba, DN: CN=JimH.OU=East.O=XYZCorp.T=W2K_EDIR_873 -Value CTS : 01/16/2004 11:00:32 PM R = 0001 E = 0003 -Value MTS = 01/16/2004 11:00:32 PM R = 0001 E = 0003, Type = 000c USED_BY, -Flags = 0002 OK_TO_PURGE -Used by: Resource type = 00000000, Event type = 00000003, Resource ID = 00008065, T=W2K_EDIR_873 Checked 0 external references Found: 3 total obituaries in this dib, 3 Unprocessed obits, 0 Purgeable obits, 1 OK_To_Purge obits, 0 Notified obits *** END ***
As with a Rename request, a Backlink obituary is generated in addition to the Dead obituary; a Used By obit is also generated. And as with the rename operation, these obituaries do not cause any delay in creating an object with the same name. Moving Objects The final object-level operation to examine is the move object operation. This operation is more complex than the other object-level operations and differs slightly from them because of the added complexity. The first difference between moving an object and performing any other object-level operation is that a Move request requires communication with the server that holds the Master replica of the object. If an object is moved across a partition boundary, communication with the servers that hold the Master replicas of both partitions is required. In addition, those servers must be able to communicate with each other in order for an object's data to be moved from one partition to the other. For simplicity, let's examine an object move within a partition ( User object PKuo from East.XYZCorp to West.XYZCorp ) because this operation does not vary much between a single server operation and a multiserver operation. In Listing 6.11, you start by reading object information, using DS verb DSV_READ_ENTRY_INFO (decimal value 2), for the source organizational unit (OU) and destination OU. The request made for the objects is by ID, and the reply buffers contain information about the object: the container class and the full DN of the container in question. Listing 6.11. DSA Read Entry Information Requests for the Source and Destination Containers in Preparation for an Object Move DSA: DSACommonRequest(2) conn:3 for client <JIM> DSA REQUEST BUFFER: 02 00 00 00 01 00 00 00 1D 28 00 00 E3 02 00 12 ................ DSA REPLY BUFFER: 1D 28 00 00 04 00 00 00 01 00 00 00 4F E3 8F 36 ............O..6 28 00 00 00 4F 00 72 00 67 00 61 00 6E 00 69 00 ....O.r.g.a.n.i. 7A 00 61 00 74 00 69 00 6F 00 6E 00 61 00 6C 00 z.a.t.i.o.n.a.l. 20 00 55 00 6E 00 69 00 74 00 00 00 1A 00 00 00 ..U.n.i.t....... 45 00 61 00 73 00 74 00 2E 00 58 00 59 00 5A 00 E.a.s.t...X.Y.Z. 43 00 6F 00 72 00 70 00 00 00 C.o.r.p... DSA: DSACommonRequest(2) conn:3 for client <JIM> DSA REQUEST BUFFER: 02 00 00 00 00 00 00 00 1D 28 02 00 E2 02 00 12 ................ DSA REPLY BUFFER: 1D 28 02 00 04 00 00 00 01 00 00 00 5B E3 8F 36 ...............6 28 00 00 00 4F 00 72 00 67 00 61 00 6E 00 69 00 ....O.r.g.a.n.i. 7A 00 61 00 74 00 69 00 6F 00 6E 00 61 00 6C 00 z.a.t.i.o.n.a.l. 20 00 55 00 6E 00 69 00 74 00 00 00 24 00 00 00 ..U.n.i.t....... 4F 00 55 00 3D 00 57 00 65 00 73 00 74 00 2E 00 O.U...W.e.s.t... 4F 00 3D 00 58 00 59 00 5A 00 43 00 6F 00 72 00 O...X.Y.Z.C.o.r. 70 00 00 00 28 00 00 00 4F 00 72 00 67 00 61 00 p.......O.r.g.a. 6E 00 69 00 7A 00 61 00 74 00 69 00 6F 00 6E 00 n.i.z.a.t.i.o.n. 61 00 6C 00 20 00 55 00 6E 00 69 00 74 00 00 00 a.l...U.n.i.t...
These requests validate that the source and target containers are known to the client, and they ensure that the client is communicating with the server that holds the Master copy of the object and the server that will hold the Master copy of the object. Next, you see a Read request to obtain information about the actual object being moved. This is shown in Listing 6.12. Listing 6.12. DSA Read Entry Information for an Object Being Moved DSA: DSACommonRequest(2) conn:3 for client <JIM> DSA REQUEST BUFFER: 02 00 00 00 00 00 00 00 1D 28 02 00 BC 02 00 0E ................ DSA REPLY BUFFER: 1D 28 02 00 00 00 00 00 00 00 00 00 6F 5E 90 36 ............o..6 0A 00 00 00 55 00 73 00 65 00 72 00 00 00 00 00 ....U.s.e.r..... 34 00 00 00 43 00 4E 00 3D 00 50 00 4B 00 75 00 4...C.N...P.K.u. 6F 00 2E 00 4F 00 55 00 3D 00 45 00 61 00 73 00 o...O.U...E.a.s. 74 00 2E 00 4F 00 3D 00 58 00 59 00 5A 00 43 00 t...O...X.Y.Z.C. 6F 00 72 00 70 00 00 00 0A 00 00 00 55 00 73 00 o.r.p.......U.s. 65 00 72 00 00 00 e.r...
The next step in the move process is to issue a start move operation (DS verb DSV_BEGIN_MOVE_ENTRY , decimal value 42). This request, shown in Listing 6.13, involves the name of the object and the server involved in the communications. Starting at offset 16, you can see the object name, and at offset 32, the FQDN of the server. Listing 6.13. A DSA Start Move Operation DSA: DSACommonRequest(42) conn:3 for client <JIM> DSA REQUEST BUFFER: 00 00 00 00 00 00 00 00 E3 02 00 12 0A 00 00 00 ................ 50 00 4B 00 75 00 6F 00 00 00 0C 01 2A 00 00 00 P.K.u.o......... 43 00 4E 00 3D 00 42 00 45 00 54 00 45 00 4C 00 C.N...B.E.T.E.L. 47 00 45 00 55 00 53 00 45 00 2E 00 4F 00 55 00 G.E.U.S.E...O.U. 3D 00 6F 00 6D 00 65 00 45 00 61 00 73 00 3D 00 ..E.a.s.t...O... 58 00 59 00 5A 00 43 00 6F 00 72 00 70 00 00 00 X.Y.Z.C.o.r.p... C8 00 .. DSA REPLY BUFFER:
At this point, the obituaries are issued for the moved object as well as for the object in its new location. Listing 6.14 shows the DSRepair log after an exref check is performed. Listing 6.14. Obituaries Issued Due to a Move Operation /*************************************************************/ Directory Services Repair 10550.61, DS 10550.98 Log file for server ".BETELGEUSE.DreamLAN.W2K_EDIR_873." in tree "W2K_EDIR_873" External Reference Check Start: 01/17/2004 03:11:07 AM Local Time (1) Found obituary for: EID: 0e0002bd, DN: CN=PKuo.OU=East.O=XYZCorp.T=W2K_EDIR_873 -Value CTS : 01/17/2004 03:10:43 AM R = 0001 E = 0026 -Value MTS = 01/17/2004 03:10:43 AM R = 0001 E = 0026, Type = 0002 MOVED, -Flags = 0000 - MoveObit: destID = 0e0002bc , CN= PKuo.OU=West.O=XYZCorp.T=W2K_EDIR_873 (2) Found obituary for: EID: 0e0002bd, DN: CN=PKuo.OU=East.O=XYZCorp.T=W2K_EDIR_873 -Value CTS : 01/17/2004 03:10:43 AM R = 0001 E = 0028 -Value MTS = 01/17/2004 03:10:43 AM R = 0001 E = 0028, Type = 0006 BACKLINK, -Flags = 0000 -Backlink: Type = 00000002 MOVED, RemoteID = ffffffff, ServerID = 000080a3, CN=RIGEL.O=eDir_Book.T=W2K_EDIR_873 (3) Found obituary for: EID: 0e0002bd, DN: CN=PKuo.OU=East.O=XYZCorp.T=W2K_EDIR_873 -Value CTS : 01/17/2004 03:10:43 AM R = 0001 E = 002a -Value MTS = 01/17/2004 03:10:43 AM R = 0001 E = 002a, Type = 000c USED_BY, -Flags = 0002 OK_TO_PURGE -Used by: Resource type = 00000000, Event type = 00000001, Resource ID = 00008065, T=W2K_EDIR_873 (4) Found obituary for: EID: 0e0002bc, DN: CN=PKuo.OU=West.O=XYZCorp.T=W2K_EDIR_873 -Value CTS : 01/17/2004 03:10:43 AM R = 0001 E = 0021 -Value MTS = 01/17/2004 03:10:43 AM R = 0001 E = 0021, Type = 0003 INHIBIT_MOVE, -Flags = 0000 Checked 0 external references Found: 4 total obituaries in this dib, 3 Unprocessed obits, 0 Purgeable obits, 1 OK_To_Purge obits, 0 Notified obits *** END ***
NOTE When an object is moved, it is essentially deleted from its original context and re-created in the target context. However, the entry ID is preserved. You accomplish this by first changing the entry ID of the object in the source context (refer to obits 1 and 4 in Listing 6.14) and then assigning the original entry ID to the object in the new context.
Now you see more differences between the move operation and the previously described object operations. The Inhibit Move obituary issued for the new object (Obit 4 in Listing 6.14) blocks further operations (except modify) on the object, including renames, deletions, and moves until the move operation is completed. It is possible to change the attributes of the object, but all other requests receive a -637 error "previous move in progress"). This is one of the most common error messages received while performing administrative tasks . If you understand how the move process operates, you can understand what a -637 error means and know what needs to be done to resolve the situation. NOTE Although the target object can only be manipulated in a minimal number of ways because of the Move Inhibit obituary, a new object with the same name can be created in the original location. The Moved obituary type does not prevent object creation.
As with the previous object operations, with this operation, you also have a Backlink obituary created. When the move is complete, DS requests that the move be finished by issuing DS verb DSV_FINISH_MOVE_ENTRY (decimal value 43). This initiates the purge process for the Move Inhibit and Moved obituaries. Listing 6.15 shows this request. Listing 6.15. A DSA Finish Move Operation DSA: DSACommonRequest(43) conn:3 for client <JIM> DSA REQUEST BUFFER: 00 00 00 00 01 00 00 00 BC 02 00 0E E3 02 00 12 ................ 0A 00 00 00 50 00 4B 00 75 00 6F 00 00 00 6F 00 ....P.K.u.o...o. 2A 00 00 00 43 00 4E 00 3D 00 42 00 45 00 54 00 ....C.N...B.E.T. 45 00 4C 00 47 00 45 00 55 00 53 00 45 00 2E 00 E.L.G.E.U.S.E... 4F 00 55 00 3D 00 6F 00 6D 00 65 00 45 00 61 00 O.U...E.a.s.t... 73 00 3D 00 58 00 59 00 5A 00 43 00 6F 00 72 00 O...X.Y.Z.C.o.r. 70 00 00 00 65 00 p...e.
The finish move operation completes, and the obituary purge process begins. When the obituaries are purged, you can proceed with other move operations, and you can rename the object or delete it. However, if you try to delete an object that was just moved without waiting for its associated obits to be purged, you will get a response similar to that shown in Listing 6.16. Listing 6.16. A Delete Request on an Object with a Previous Move in Progress DSA: DSACommonRequest(8) conn:16 for client <JIM> DSA REQUEST BUFFER: 00 00 00 00 BC 02 00 0E ........ DSA REPLY BUFFER: DSA: DSACommonRequest(8): returning ERROR -637
The error message in the reply buffer is expected in this case: -637 error ("previous move in progress"). This error occurs because the obituaries created for the Move request have not yet purged, even though the finish move operation has executed successfully. You can retry in a short while and succeed. However, if the error is not cleared after some time (say, 10 minutes), you should check server-to-server communications and determine why the obits are not being purged. | 