OMget_array

Synopsis

int OMget_array (
OMobj_id object_id,
int *type,
char **array_ptr,
int *ndims,
int *dims,
int mode );

int OMXobj::get_array(
int *type,
char **array,
int *ndim,
int *dims,
int mode );

Description

Most users do not need the complete generality provided by the OMget_array routine. You should first try to use the simplified wrapper routines OMret_array_ptr and OMret_typed_array_ptr .

OMget_array gets the value of an array object but unlike the other "get" routines can also be used to set the value of the array. The mode parameter indicates how the program intends to use the array: for read-only, write-only, or read-write access.

The type , ndims , and dims parameters are read-write arguments that allow you to constrain the returned value for the array. The type parameter can either be used to constrain the data type so that only a specific type of data is returned or can be left unconstrained so that the most efficient data type is returned. For example, if you want to get an array of type float, set the initial value of the type parameter to OM_TYPE_FLOAT before making the call. If the array cannot satisfy the call, OMget_array will attempt to convert the array to the requested type, but will return an error rather than an array of the wrong type. If you want an unconstrained data type, use the value OM_TYPE_UNSET. If the type parameter is not set before calling OMget_array, the routine usually fails, depending on the type of the field.

The ndims and dims parameters can be used to either constrain the call to return only a specific array dimensionality or to leave the dimensions unconstrained. To constrain the number of dimensions of the returned array, set ndims to a non-zero value. To leave the dimensions unconstrained, you should initially specify the ndims argument as 0; the dimensions of the array are then returned in ndims when the call is complete.

The dims parameter depends on the value of the ndims parameter. If ndims is non-zero (that is, the array is constrained), dims must specify the value for each dimension. If ndims is 0 (that is, the array is unconstrained), dims will be returned; in this case, declare dims as int dims[OM_ARRAY_MAXDIM]; .

Note: The OMget_array routine works on arrays of primitives only -- not on arrays of groups or arrays of strings. For details of the calls appropriate for handling arrays of groups, please see OMget_array_val, OMset_array_val, OMdel_array_val . For details of the calls appropriate for handling arrays of strings, please see OMget_str_array_val and OMset_str_array_val

The OMget_array routine is designed to minimize copying the array. In some situations, you are given a pointer to the same piece of memory that AVS/Express is using to store the memory for the array.

Here is an outline of what happens on a call to OMget_array. For details, see the table following the argument descriptions.

Depending on mode , array_ptr , and whether the array is local to the calling process, AVS/Express does one of the following:

Makes a copy of the array, placing it in the calling function's process, and returns a pointer to that copy

Returns a pointer to the Object Manager's copy of the array

The program works on the array. Results are undefined if the program performs an action inconsistent with the mode in which the array was retrieved.

When the program has finished working on the array, if the array_pointer was NULL, the program must call ARRfree. Depending on mode , array_ptr , and whether the data is local to the calling process, AVS/Express does one or both of the following:

• Copies the array back into the Object Manager

• Generates a notification that the array object has been changed

Arguments

object_id

The id of an array object.

type

As an output argument, indicates the array's type. AVS/Express provides the following symbolic constants, defined in <avs/om.h>:

Type	Meaning
OM_TYPE_CHAR	Character
OM_TYPE_BYTE	Byte
OM_TYPE_SHORT	Short integer
OM_TYPE_INT	Integer
OM_TYPE_FLOAT	Single-precision floating-point
OM_TYPE_DOUBLE	Double-precision floating-point
OM_TYPE_PTR	Pointer
OM_TYPE_UNSET	Not set (i.e., it was created with base type prim)

array_ptr

The array's address. array_ptr must be a variable. array_ptr is both an input and an output argument.

On input, if array_ptr is not NULL, AVS/Express returns the array into the specified address. This array must contain enough memory to hold the resulting array. If array_ptr is NULL, AVS/Express returns the array into an address of its choosing.

array_ptr must be NULL if the mode is OM_GET_ARRAY_WR or OM_GET_ARRAY_RW.

On output, array_ptr is set to the address of the array.

ndims

Determines whether the number of dimensions of the returned array should be constrained.If ndims is set to 0, the dimensions of the array are unconstrained and when the call is completed, ndims contains the number of dimensions in the returned array. If non-zero, the dims array should contain an array of ndims values specifying constraints for the dimensions of the array. This value must be set before the call to OMget_array is made.

dims

If the ndims argument is set to a non-zero value, this array should contain an array of ndims values specifying constraints for the dimensions of the array. If the ndims argument was specified as 0, this array is set by the OMget_array call to contain the dimensions of the returned array. The first element of the array is set to the size of the fastest varying dimension. This is the rightmost value in the V specification.

dims should be an integer array large enough for the maximum number of dimensions that can be returned. The constant OM_ARRAY_MAXDIM specifies the maximum number of dimensions allowed by AVS/Express.

mode

The mode, indicating how the program intends to use 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.

For details on the different modes, see the table below.

Returned value

The status code (see Return Status ).

If the calling process specifies NULL for array_pointer , it must call ARRfree after it has finished processing the array. This prompts AVS/Express to perform a set of actions. The actions differ depending on the circumstances. See the table below.

The following action table describes what happens with OMget_array under different conditions. ("Local" means that the array is local to the calling process).

If array_ptr is specified as...	and the array is...	then the following occurs depending on the mode...
RD	RD_COPY	RW	WR
NULL	Local	P/A	C/A	P/A/N	P/A/N
External	C/A	C/A	C/A/W/N	P/A/W/N
Not NULL	Local	C	C	not appl. array_ptr must be NULL.	not appl. array_ptr must be NULL.
External	C	C

Code	Meaning
P	On the call to OMget_array, AVS/Express returns a pointer to the Object Manager's copy of the array. The process then reads directly from and/or writes directly to the Object Manager's copy. In the case of WR mode for an external array, AVS/Express allocates space for the array in the calling process and returns a pointer to that array.
C	On the call to OMget_array, AVS/Express makes a copy of the array and returns a pointer to the copy.
A	The program must call ARRfree when finished working on the array.
W	On the call to ARRfree, AVS/Express replaces the original copy of the array.
N	On the call to ARRfree, AVS/Express generates a notification that the array object has been changed.

Example

/* Get the contents of an array for reading and writing. */
OMobj_id array_id;
/* Constrain the data type. */
int array_type = OM_TYPE_FLOAT;// force type to float array
float *array = NULL;
/* Don't constrain dims */
int ndims = 0;
int dimension_size[OM_ARRAY_MAXDIM];
int index, number_of_elements;
int status;
...
status = OMget_array(array_id, &array_type, (char **) &array,
&ndims, dimension_size, OM_GET_ARRAY_RW);

if (status != 1) {
printf("error occurred\n");
return(0);
}

/* Determine the number of elements in the array. */
number_of_elements = 1;
for (index=0;index<ndims;index++)
number_of_elements *= dimension_size[index];

/* Multiply each element of the array by 2. */
for(index=0; index<number_of_elements; index++)
array[index] *= 2 * array[index];

/* After processing the array, call ARRfree to decrement the
arrays internal reference counter and to trigger updates.*/
ARRfree(array);