OMret_typed_array

OMret_typed_array_ptr

Synopsis

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

void *OMXobj::ret_typed_array_ptr(
int mode,
int type,
int *size);

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 the 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. It is useful, in particular, when you need to define the data type for an object that does not have a defined data type or whose data type is different than the type of data you want to operate on.

If you have an object defined in V like

prim foo[3];

this routine defines the data type of the array to be the type specified by the type argument.

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.

type

This argument specifies the type of the array to return. If the array is not yet defined, it is created of this type. If the array is defined, it is converted into the type specified using normal C casting rules. The type value can be one of the data types described for OMget_data_type except for OM_TYPE_STRING and OM_TYPE_PTR.

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.

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.