OMget_str_val, OMset_str_val, OMget_name_str_val, OMset_name_str_val

Synopsis

int  OMget_str_val (
OMobj_id  object_id,
char   **value,
int maxlen  );

int  OMset_str_val (
OMobj_id  object_id,
const char *value  );

int  OMget_name_str_val (
OMobj_id  object_id,
OMobj_name  subobject_name,
char   **value,
int maxlen  );

int  OMset_name_str_val (
OMobj_id  object_id,
OMobj_name  subobject_name,
const char  *value  );

int  OMXstr::get_str_val( const char *value  );

int OMXobj::set_str_val( char **value, char *default = 0  );

Description

These routines get and set an string object's value.

The routines access the target object in different ways.

Arguments

object_id

The id of an object.

subobject_name

The name of one of object_id 's immediate subobjects.

value

In OMget_str_val and OMget_name_str_val and , an output argument containing the object's value as a string. If value is NULL when passed into OMget_str_val and OMget_name_str_val, then value is set to a string is allocated by the OM and the calling program should free the returned string. OMXstr::get_str_val is similar but do NOT free the return value; the OMXstr class automatically manages the string storage.

In OMset_str_val, and OMset_name_str_val, an input argument specifying object_id's new string value. The OM will make a copy of the input string.

maxlen

The length of the string when the string is allocated prior to to the call to OMget_str_val. This will be the maximum number of characters the OM will copy into the string. If maxlen is 0, then the OM will allocate storage long enough to hold the entire string and set the value pointer.

default

In OMXstr::get_str_val, the value to return if the object does not have a valid string value.

Returned value

The status code (see See Return Status ).

Example 1

/* Get and set object var1_id's value. */
OMobj_id  var1_id;
int status;
char *var1_value = NULL;
...
status = OMget_str_val(var1_id, &var1_value, 0);

if (status == 1) {
printf( "Strings value is %s\n", var1_value);
free(var1_value);
val1_value = strdup("New value");
status = OMset_str_val(var1_id, var1_value);
free(var1_value);
}

Example 2

/* Get and set object var1_id's value using a pre-allocated string */
OMobj_id  var1_id;
int status;
char var1_value[100];
...
status = OMget_str_val(var1_id, &var1_value, sizeof(var1_value));

if (status == 1) {
printf( "Strings value is %s\n", var1_value);
strcpy(val1_value, "New value");
status = OMset_str_val(var1_id, var1_value);
}