OMfind_subobj, OMlookup_subobj and OMfind_obj
Synopsis
OMobj_id  OMfind_subobj (
                OMobj_id  parent_id,
                OMobj_name  search_name,                
     
     
      int  mode  );
OMobj_id  OMlookup_subobj (
                OMobj_id  parent_id,
                OMobj_name  search_name,                
     
     
      int  mode  );
OMobj_id  OMfind_obj (
                OMobj_id  object_id,
                OMobj_name  search_name,              
     
     
      int  mode  );
Description
These routines search for an object, which you specify by name, and return the object's id.
The routines differ in the scope of their search.
| This routine... 
 | confines its search to... 
 | 
| OMfind_subobj | I mmediate subobjects of parent_id. This is the routine you typically call. | 
| OMlookup_subobj | Any subobject of parent_id , including immediate subobjects and lower-level subobjects. If multiple instances of search_name exist, AVS/Express returns the id of the first one it finds. | 
| OMfind_obj | The following objects, in order:  The object specified by object_id .  The immediate subobjects of object_id .  An ancestor of object_id . | 
These routines extend their search beyond the scope described above when they encounter a global library object as a subobject. In this case, they will search through the subobjects of the global library as well. This functionality can be disabled by OR'ing in the flag OM_FIND_NO_LIBRARIES into the mode argument.
Arguments
parent_id
object_id
An object id. The search is performed in the context of this object.
search_name
The unqualified name of the object to find.
mode
Indication of how the process intends to use the object.
| Mode 
 | Meaning 
 | 
| OM_OBJ_RD | The process intends to read the object, but not write to it (or any object that it might get using this id). | 
| OM_OBJ_RW | The process intends to read and possibly write to the object. | 
Consider the following V code:
group g {
        int a=1;
};
g g1;
When g1 is created, AVS/Express does not immediately create its subobjects. Rather, for each subobject, AVS/Express waits until the subobject is actually referenced, for example, a value is assigned to it.
If mode is OM_OBJ_RD and the subobject has not yet been created, AVS/Express returns instead the id of the template subobject, in this example, g.a. This works provided the program intends only to read the object.
If mode is OM_OBJ_RW, AVS/Express always returns the id of the subobject, in this example, g1.a. If the subobject does not yet exist, AVS/Express creates it.
Optionally, you can OR into the mode parameter additional flags to qualify the object search.
| Flag 
 | Meaning 
 | 
| OM_FIND_NO_LIBRARIES | Do not search recursively for subobjects in global libraries. | 
| OM_FIND_NO_VIRTUAL | Do not search for virtual objects. | 
| OM_SUB_TEMPL | If parent_id is a group pointer or reference, by default AVS/Express returns the id of parent_id 's subobject. OM_SUB_TEMPL specifies that AVS/Express should instead return the id of the subobject in parent_id 's template object. | 
Returned value
The returned value is either the found object's id or, if OMfind_obj failed, OMnull_obj(see Return Status ).
Example 1
/* Find subobject x. Its parent's id is grp1_id. */
OMobj_id grp1_id, x_id;
...
x_id = OMfind_subobj(grp1_id, OMstr_to_name("x"), 
                                                        OM_OBJ_RD);
if OMis_null_obj(x_id)
        printf("Error searching for x\n");
Example 2
/* Find object x in the context of the object whose id
   is grp1_id. */
OMobj_id grp1_id, x_id;
...
x_id = OMfind_obj(grp1_id, OMstr_to_name("x"), OM_OBJ_RD);
if (OMis_null_obj(x_id)) 
        printf("Error searching for x\n");