OMget_array_subobj

Synopsis

int OMget_array_subobj (OMobj_id _object_id,int_subobject_index,
OMobj_id *subobject_id,int_mode );

Description

OMget_array_subobj treats the immediate subobjects of object_id as an array of objects and returns the id of the specified subobject. You identify the subobject in terms of its index into the array. Use this routine in conjunction with the routine OMget_num_subobjs to traverse the list of subobjects of a hierarchical object.

Arguments

object_id

The id of an object with subobjects.

subobject_index

The index of a subobject. AVS/Express uses 0-based indexing; i.e., the index of the first subobject is 0.

subobject_id

An output argument, set to the id of the requested subobject.

mode

The access mode indicating how the calling process intends to use the subobject:

Mode

Meaning

OM_OBJ_RD

The program intends to read the subobject, but not write to it.

OM_OBJ_RW

The program intends to read and possibly write to the subobject.

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, when 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.

Returned value

The status code (see Return Status ).

Examples

Given the following V code group grp1 { int a; int b; int c; };

The following C statements return the ids of the subobjects. Assume grp1_id is set to the id of object grp1:

OMobj_id grp1_id, subobjs[10];
int i;
int num;
int status;
...
status = OMget_num_subobjs (grp1_id, &num);
for (i=0; i < num; i++)
status = OMget_array_subobj(grp1_id, i, &subobjs[i],
OM_OBJ_RD);

See Also

OMget_num_subobjs