Object data is stored in two parts as shown in Figure 7-1.

Figure 7-1. ToolTalk Object Data

One part is called the object content. The object content is managed by the application that creates or manages the object and is typically a piece, or pieces, of an ordinary file: a paragraph, a source code function, or a range of spreadsheet cells, for example.

The second part is called the object specification (spec). A spec contains standard properties such as the type of object, the name of the file in which the object contents are located, and the object owner. Applications can also add their own properties to a spec, for example, the location of the object content within a file. Because applications can store additional information in specs, you can identify data in existing files as objects without changing the formats of the files. You can also create objects of pieces of read-only files. Applications create and write specs to the ToolTalk database managed by rpc.ttdbserverd.

---

Note: You cannot create objects in files that reside in a read-only file system. The ToolTalk service must be able to create a database in the same file system that contains the object.

---

A ToolTalk object is a portion of application data for which a ToolTalk spec has been created.

To assign an otype for the object spec, use tt_spec_type_set(). You must set the type before the spec is written for the first time. It cannot be changed.

---

Note: If you create an object spec without assigning an otype or with an otype that is unknown to the types database, messages addressed to the object cannot be delivered. (The ToolTalk service does not verify that the otype you specified is known to the types database.)

---

You can determine what properties you want associated with an object; you add these properties to a spec. The ToolTalk service recognizes that it is not always possible to store information in your own internal data; for example, the objid for objects in plain ASCII text files. You can store the location of the objid in a spec property and then use this location to identify where the object is in your tool's internal data structures.

The spec properties are also a convenience for the user. A user may want to associate properties (such as a comment or object name) with the object that they can view later. Your application or another ToolTalk-based tool can search for and display these properties for the user.

To store properties in a spec, use tt_spec_prop_set().

To add to the list of values associated with the property, use tt_spec_prop_add().

You can examine the following spec information with the specified ToolTalk functions:

To compare two objids, use tt_objid_equal(). tt_objid_equal()returns a value of 1 even in the case where one objid is a forwarding pointer for the other.

Create a filter function to query for specific specs in a file and obtain the specs in which you are interested.

Use tt_file_objects_query() to find all the objects in the named file. As the ToolTalk service finds each object, it calls your filter function, and passes it the objid of the object and the two application-supplied pointers. Your filter function does some computation and returns a Tt_filter_action value (TT_FILTER_CONTINUE or TT_FILTER_STOP) to either continue the query, or to quit the search and return immediately.

The following sample code illustrates how to obtain a list of specs:

/* 
 * Called to update the scrolling list of objects for a file. 
 * Uses tt_file_objects_query to find all the ToolTalk objects.
 */
int
cntl_update_obj_panel()
{
       static int list_item = 0;
   char *file;
   int i;

   cntl_objid = (char *)0;

   for (i = list_item; i >= 0; i--) {
   xv_set(cntl_ui_olist, PANEL_LIST_DELETE, i, NULL);
}


list_item = 0;
file = (char *)xv_get(cntl_ui_file_field, PANEL_VALUE);
if (tt_file_objects_query(file,
        if (tt_file_objects_query(file,
                                 (Tt_filter_function)cntl_gather_specs,
                                  &list_item, NULL) != TT_OK) 

{
     xv_set(cntl_ui_base_window, FRAME_LEFT_FOOTER,
            “Couldn't query objects for file”, NULL);
     return 0;
   }

   return 1;
}

Within the tt_file_objects_query() function, the application calls cntl_gather_specs, a filter function that inserts objects into a scrolling list.

/* 
 * Function to insert the objid given into the scrolling lists
 * of objects for a file. Used inside tt_file_objects_query as
 * it iterates through all the ToolTalk objects in a file.
 */
Tt_filter_action
cntl_gather_specs(objid, list_count, acc)
     char *objid;
     void *list_count;
     void *acc;
{
   int *i = (int *)list_count;

   xv_set(cntl_ui_olist, PANEL_LIST_INSERT, *i,
       PANEL_LIST_STRING, *i, objid,
       NULL);

   *i = (*i + 1);

    /* continue processing */
    return TT_FILTER_CONTINUE;
}

The objid contains a pointer to a particular file system where the spec information is stored. To keep spec information as available as the object described by the spec, the ToolTalk service stores the spec information on the same file system as the object. Therefore, if the object moves, the spec must move, too.

Use tt_spec_move() to notify the ToolTalk service when an object moves from one file to another (for example, through a cut and paste operation).

If a new objid is not required (because both the new and old files are in the same file system), the ToolTalk service returns TT_WRN_SAME_OBJID.

If the object moved to another file system, the ToolTalk service returns a new objid for the object and leaves a forwarding pointer in the ToolTalk database from the old objid to the new one.

When your process sends a message to an out-of-date objid (that is, one with a forwarding pointer), tt_message_send() returns a special status code, TT_WRN_STALE_OBJID, and replaces the object attribute in the message with a new objid that points to the same object in the new location.

---

Note: Update any internal data structures that reference the object with the new objid.

---

To keep the ToolTalk database that services the disk partition where a file that contains object data is stored up-to-date, use the ToolTalk functions to copy, move, or destroy the file. Table 7-3 lists the ToolTalk functions you use to manage files that contain object data.

The ToolTalk service provides ToolTalk-enhanced shell commands to copy, move, and remove ToolTalk object and file information. Table 7-4 lists the ToolTalk-enhanced shell commands that you and users of your application should use to copy, move, and remove files referenced in messages and files that contain objects.