OMfind_subobj, OMlookup_subobj and OMfind

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");