OMget_array_val, OMset_array_val, OMdel_array_val
Synopsis
int OMget_array_val (
OMobj_id object_id,
int value_index,
OMobj_id *value_id,
int mode );
int OMset_array_val (
OMobj_id object_id,
int value_index,
OMobj_id value_id );
int OMdel_array_val (
OMobj_id object_id,
OMobj_id value_id );
Description
These routines get, set, or delete an object id in a one-dimensional array of groups, modules or macros.
The object is either an array of pointers/references to other objects or a by-value group array.
|
The object can be...
|
Description
|
|
An array of pointers/references to other objects |
For example, the V code below defines object my_images as a one-dimensional array of references (&) to other objects: • image &my_images[] = {im1,im2,im3}; The routines operate on the object ids specified in the value parameter. For example, in a call to OMget_array_val, if value_index is 0, AVS/Express returns the id of the first object in the list, in this case, im1. |
|
A by-value group array |
For example, the V code below defines object coordinates as a one-dimensional group array with subobjects:
•
group coordinates[4] {
Internally, coordinates is actually four group objects, each with its own id. The routines operate on the object ids of each occurrence of the group. For example, in a call to OMget_array_val, if value_index is 0, AVS/Express returns the id of the first occurrence of coordinates. |
In some cases, the OMget_array_val routine returns the OMobj_id of a link object and not the end value in and of itself. It is a good practice to use the routine OMget_obj_val, OMget_obj_pval, and OMset_obj_val on the return value from OMget_array_val and to check the status return of that routine. This problem occurs in the following V definition:
group &v1;
group &v_arr[] => {v1};
The OMget_array_val routine will return the id of v1 which does not have a valid value at this time. The call OMget_obj_val returns 0 in this case.
OMset_array_val only works when the array object's reference mode is by-reference or by-pointer, not by-value. It has two different behaviors depending upon whether the dimensions of the array are explicitly defined or not defined. If the V definition of the object looks like
group &arr[]; // array dimensions not defined
the OMset_array_val call inserts the new value into the array at the specified location, moving forward the contents of the array, and increasing the array's size by one. If you specify the value_index parameter with the constant OM_ARRAY_APPEND, a new value is added onto the end of the array.
If the V definition looks like
group a, b, c;
group &foo[3] => {a, b, c};
the OMset_array_val call replaces the object specified index with the object value specified with the value_id parameter.
OMdel_array_val deletes an object's reference to another object, but does not delete that other object. You can use OMdel_array_val when the object's mode is by-reference or by-pointer, but not when its mode is by-value.
Arguments
object_id
The id of an object. The object must be a one-dimensional array of pointers (* mode) or references (& mode) to other objects.
value_index
An array value. AVS/Express uses 0-based indexing; i.e., the index of the first value in an array is 0.
In OMset_array_val, index can be OM_ARRAY_APPEND, meaning that the object should be added to the end of the array.
value_id
In OMget_array_val, the id of the specified object.
In OMset_array_val, the id of the object to place into the array.
In OMdel_array_val, the id of the object to be deleted from the array.
mode
In a call to OMget_array_val, the access mode indicating how the process intends to use the subobject:
|
Mode
|
Meaning
|
|
OM_OBJ_RD |
The process intends to read the subobject, but not write to it. |
|
OM_OBJ_RW |
The process intends to read and possibly write to the subobject. |
Consider the following V code:
group coordinates[4]
int x=100, y=200;
};
When coordinates is created, AVS/Express does not immediately create all four occurrences of it. Rather, AVS/Express creates a template copy of the group, then, for each occurrence, waits until the occurrence is actually referenced, for example, when a value is assigned to one of its subobjects.
If mode is OM_OBJ_RD and the occurrence has not yet been created, AVS/Express returns instead the id of the template occurrence. 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 occurrence. If the occurrence does not yet exist, AVS/Express creates it.
Returned value
A status code. See Return Status .
Example
A V file contains the following definitions:
image a, b, c, d, e;
image &my_images[] = {a,b,c};
The following code illustrates how you can modify the values in my_images:
OMobj_id a_id, b_id, c_id, d_id, e_id, my_images_id;
OMobj_id parent_object;
OMobj_id returned_id;
int status;
...
/* Get the object ids of the images. */
a_id = OMfind_subobj(parent_object, OMstr_to_name("a"),
OM_OBJ_RD);
... /* Same for the other objects. The mode for my_images_id is
OM_OBJ_RW. */
/* Get the object id of the first value in my_images. */
status = OMget_array_val(my_images_id, 0, &returned_id,
OM_OBJ_RD);
/* Set the second value in my_images to object d. */
status = OMset_array_val(my_images_id, 1, d_id);
/* Add object e to the end of my_images. */
status = OMset_array_val(my_images_id, OM_ARRAY_APPEND, e_id);
/* Delete object c from my_images. */
status = OMdel_array_val(my_imdages_id, c_id);