OMget_str_array_val and OMset_str_array_val
Synopsis
int OMget_str_array_val (
OMobj_id object_id,
int value_index,
char **value,
int maximum_size );
int OMset_str_array_val (
OMobj_id object_id,
int value_index,
const char *value );
Description
These routines get and set values in an object that is a one-dimensional array of strings. To get a string array's value, you may find it easier to use the routine OMret_str_array_val.
For example, the V code below defines an object called labels as a one-dimensional array of strings:
string labels[] = {"Open", "Close"};
Arguments
object_id
The id of an object. The object must be a one-dimensional array of strings.
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_str_array_val, index can be OM_ARRAY_APPEND, meaning that the object should be added to the end of the array.
value
In OMget_str_array_val, an output argument containing the string. AVS/Express either allocates space for the string or places the array in an address you specify:
|
If value is...
|
then AVS/Express...
|
|
NULL |
Allocates space for the string using malloc and returns the string's address in value. AVS/Express ignores the maximum_size argument. After processing the string, you must free the space with the C library routine free (not ARRfree). |
|
An address |
Writes the string to the address pointed to by value . The maximum_size argument indicates the maximum number of characters to write. |
In OMset_str_array_val, value is an input argument specifying the address of the new string.
maximum_size
In OMget_str_array_str_val, the maximum number of characters to get. This argument is ignored if value is a NULL pointer.
Returned value
A status code. See Return Status .
Example 1
The following V code defines an array of strings:
string labels[] = {"Open", "Close"};
The code segment below gets the first object of the string. OMget_str_val allocates space for the array:
/* Get a string. OMget_str_array_val allocates space. */
OMobj_id str1_id;
int status;
char *str1_val = NULL;
...
status = OMget_str_array_val(str1_id, 0, &str1_val, 0);
... /* Process the string. */
if (str1_val != NULL) free(str1_val);
Example 2
This example is like the first, but this time the program itself allocates space for the string:
/* Get a string. Return the string into the specified address. */
OMobj_id str1_id;
char str1_buf[128];
char *str1_ptr = str1_buf;
...
status = OMget_str_array_val(str1_id, 0, &str1_ptr,
sizeof(str1_buf));
/* Process the string. */
See also