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 ).
Example
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