OMret_array

OMret_array_ptr

Synopsis

void *OMret_array_ptr(
OMobj_id object_id,
int mode,
int *size,
int *type);

void *OMret_name_array_ptr(
OMobj_id parent_id,
OMobj_name subobject_name,
int mode,
int *size,
int *type);

void *OMXobj::ret_array_ptr(
int mode,
int *size = NULL,
int *type = NULL);

Description

Returns the array value for the object specified. This routine works only when the array dimensions of the AVS/Express object are defined before this routine is called and only works for primitive objects that are not of type ptr or string. It can be used to both read and write the value of the array object.

This routine cannot be used to define the data type or array size of an array that does not have these values already defined in the AVS/Express object. If your AVS/Express object is defined like one of these and you are using this routine for write access (i.e., you are creating the array definition), you will have to use another routine to get its value:

prim foo[3]; // use OMret_typed_array_ptr
int bar[]; // use OMset_array or OMget_array

You can always use this routine for read-only array access since, in this case, the array must already have a defined type and size in this case.

You must call the routine ARRfree on the return value of this routine (unless NULL is returned) when you are finished with the array.

This routine is a wrapper that calls OMget_array. You can use that routine if you need to define or have returned to you the dimensions of the object (instead of just the array size).

Arguments

object_id

The id of the array object.

mode

The mode in which to retrieve the value for the array:

Mode	Meaning
OM_GET_ARRAY_RD	The program intends to read the array, but not write to it.
OM_GET_ARRAY_RD_COPY	The program requires a copy of the array for its own, private use (reading or writing).
OM_GET_ARRAY_RW	The program intends to both read and write to the array.
OM_GET_ARRAY_WR	The program intends to write to the array, completely replacing it, but not read it.

size

This argument returns the number of values in the array. You can pass this argument in as NULL if you know the size of the array implicitly because of the definition of the AVS/Express object. If the array is multi-dimensional, this value is the product of all of the dimensions.

type

This argument returns the data type of the returned array. You can pass this argument as NULL if you know the data type of your array from the definition of your AVS/Express object.

Returned value

The return value for this routine is a pointer to the array. You must always call the routine ARRfree on the array pointer when you are finished with it. If the array's value is not set, a NULL pointer is returned.