| |
|
|
|
1 Object Manager Application Programming Interface
This appendix describes the routines in AVS/Express' Object Manager C and C++ Application Programming Interfaces (APIs).
Note: The Object Manager also provides a FORTRAN API which is documented separately in Appendix D.
- Organization of this appendix, Section 1.1
- Summary of routines by category, Section 1.2
- Object id, Section 1.3
- Object names, Section 1.4
- Type id, Section 1.5
- Header files, Section 1.6
- Return status, Section 1.7
- Reference pages, Sections 1.8 - 1.113
This appendix begins with a set of tables that summarize routines by functional category. Use these tables to help you find a routine you need to perform a particular task. This appendix then introduces basic data types used by the Object Manager API, then presents the routines in the API.
There are five different types of routines in this appendix:
- array allocation/deallocation routines (prefixed with ARR)
- error handling routines (prefixed with ERR)
- event handling routines (prefixed with EV)
- Object Manager manipulation routines for both C and C++ (routines prefixed by OM and classes prefixed by OMX)
- worldwide language routines (prefixed with TM)
Generally, the routines are organized alphabetically with the following exceptions:
- Get and set routines of the same data type are grouped together. For example, the routines OMget_int_val and OMset_int_val are both listed under OMget_int_val.
- Routines that take a parent object and a subobject's name are grouped with the routine that operates directly on the object itself. For example, the routine OMget_name_int_val is on the same page with OMget_int_val.
- C++ API methods that operate on an object, are grouped with the C API routine of the same name. For example, the set_int_val method is placed on the same page with the OMset_int_val routine.
When a C++ API method is documented with a C API routine, the parameters, return code, and functionality will be the same with one exception. The first argument to the C API routine is replaced by the object on which the C++ method is invoked. For example, the following C API call:
is the same as the following C++ method call:
Some C++ methods have defaulted arguments. If you do not supply a value for these arguments, the default value is supplied. In this document, the defaulted arguments are indicated in the declaration of the routine. For example:
In this definition, you can call this routine as:
If you do, NULL values are supplied for the size and type arguments.
This section summarizes the Object Manager Library routines, by category.
In the tables below, where two or more routines appear together, you can find the details for them under the entry for the first routine listed.
OMget_obj_iprop
OMget_obj_rprop
OMget_obj_sprop
OMset_obj_iprop
OMset_obj_rprop
OMset_obj_sprop
OMset_obj_iarray_prop
OMget_sub_sarray
OMget_sub_iarray
OMget_sub_farray
OMget_sub_rarray
OMset_sub_barray
OMset_sub_sarray
OMset_sub_iarray
OMset_sub_farray
OMset_sub_rarray
AVS/Express assigns each object a unique id.
In a C function, the id's type is OMobj_id.
For example, the following V code defines group object grp1 and two subobjects, a and b:
A C program can obtain the object ids of grp1, a, and b. Assume that grp1's parent id is parent_id:
OMobj_id parent_id, grp1_id, a_id, b_id;
...
grp1_id = OMfind_subobj(parent_id, OMstr_to_name("grp1"),
OM_OBJ_RW);
a_id = OMfind_subobj(grp1_id, OMstr_to_name("a"),
OM_OBJ_RW);
b_id = OMfind_subobj(grp1_id, OMstr_to_name("b"),
OM_OBJ_RW);
OMobj_id is a two-value structure defined in the header file <avs/om.h> as follows:
typedef struct _OMobj_id {
OMobj_id_type obj_id; /* Pointer within a process. */
OMproc_id proc_id; /* Process id. */
} OMobj_id;
You generally can ignore the fact that OMobj_id is a structure. But be aware that on some compilers, you cannot initialize a OMobj_id in its declaration:
To compare object ids, use the routine OMequal_objs:
To determine whether an object id is null, use the routine OMis_null_obj:
The following are variables of type OMobj_id. They are provided by the Object Manager, in <avs/om.h>, and initialized at system start-up.
Each object has a name. The name is a character string that is unique among its sibling objects in the object hierarchy.
In a C function, the object name's type is OMobj_name.
/* Get the name of the object whose id is func_id. */
OMobj_id func_id;
OMobj_name func_name;
int status;
...
status = OMget_obj_name (func_id, &func_name);
In an Object-Manager routine, where an object-name argument is optional, you can specify the following constant to indicate no object name:
The Object Manager does not store and manipulate an object's string directly, but rather allocates a unique integer value that maps directly to a particular string. OMobj_name holds that integer value.
This approach has two primary benefits: it prevents strings from being duplicated in memory; and it allows two strings to be compared with a single integer compare.
The Object Manager has routines to convert between an object name, which is an integer, and its corresponding string:
OMobj_name object_name; // An integer.
char object_string[30];
...
object_name = OMstr_to_name("My string");
strcpy(object_string, OMname_to_str(object_name));
An object's base type has a unique id.
In a C function, the id's type is OMtype_id.
OMtype_id is needed only if you are creating objects explicitly in a C function, which is not a typical use of the Object Manager.
For a program that accesses the Object Manager C API, you typically include the following basic header files:
If you use the definition of any attributes or properties, you may also need to include the header file:
If you manipulate any base types, you have to include the header file:
For a program that accesses the Object Manager C++ API, you typically include the header files:
If you use any of the routines in event handling section (these are routines prefixed with EV) you need to include the header file:
You may have to include other header files, depending on the AVS/Express kits your program accesses.
Most routines return a status code:
Some routines, when they fail with a status of OM_STAT_ERROR, generate error messages containing diagnostic information. These messages are printed to stderr. To suppress errors printed during a routine, you can "squash" errors for a duration of your code. Typically you only want to squash errors for one routine at a time. You can do this using the macro ERRsquash_start before the routine and ERRsquash_end after the routine. For example:
ERRsquash_start(); // begin suppressing errors
stat = OMget_int_val(obj_id, &val);
ERRsquash_end(); // end suppressing errors
Several routines, like OMfind_subobj, return an object id. If the routine fails, the returned value is OMnull_obj. You can test for this value with the routine OMis_null_obj. The following example attempts to get the object id of subobject x:
OMobj_id parent_id, x_id;
...
x_id = OMfind_subobj(parent_id, OMstr_to_name("x"),
OM_OBJ_RW);
if (OMis_null_obj(x_id))
printf("Error searching for x\n");
The ARR package is used by AVS/Express to maintain arrays in memory with reference counts. These arrays are typically allocated with the C malloc facility. The ARRalloc routine calls malloc and gives the resulting array a reference count of 1. The ARRfree routine decrements the reference count, and if 0, calls the free routine. There is another routine ARRincr_refcnt that adds 1 to the refcnt of an array. These arrays are identified directly by the pointer to the array.
You typically do not call ARRalloc. You only need it when you are setting an array with the OMset_array function, the mode is OM_SET_ARRAY_FREE, and you want to maintain your own reference to the array after the call. See Section 1.38, OMget_array [page 1-74].
An integer code specifying the array's data type. AVS/Express provides the following symbolic constants, defined in <avs/dtype.h>:
The size of the array, in terms of number of elements.
A pointer to the array, or NULL if ARRalloc failed.
/* Allocate space for a 100-element floating-point array. */
#include <avs/dtype.h>
int alloc_size = 100;
float *my_array;
...
my_array = (float *) ARRalloc(NULL, DTYPE_FLOAT, alloc_size, NULL);
if (my_array == NULL)
printf("Error allocating the array.\n");
ARRfree decrements an array's internal reference counter.
A process calls this routine once it has finished with an array object that was retrieved with a call to OMret_array_ptr, OMret_typed_array_ptr or OMget_array in which the array_pointer argument was NULL.
The address of the array to be freed.
See the example under OMget_array.
ARRincr_refcnt increments an array's internal reference counter. The array_ptr must have been returned from a call to ARRalloc.
You can call this routine when you want to retain your own reference to an array allocated with ARRalloc. You release this reference by calling ARRfree.
The address of the array whose reference is to be incremented.
These C macros can be used to suppress errors generated from AVS/Express library routines. Place a call to ERRsquash_start before you call a routine that may generate an error and place a corresponding call to ERRsquash_end after the routine call. Any errors generated between these calls are not presented to the user.
ERRsquash_start();
// errors generated here are not displayed
stat = OMget_int_val(obj_id, &value);
ERRsquash_end();
void EVadd_select (
int type,
int fd,
void (*function) (char *),
NULL,
char * arg,
int dir );
void EVdel_select (
int type,
int fd,
void (*function) (char *),
NULL,
char * arg,
int dir );
EVadd_select adds an event callback handler of type type.
For all types, function is a pointer to a user-supplied callback function that takes a single pointer argument. The arg parameter specifies the argument.
type can be any of the following:
- EV_SELECT0 or EV_SELECT - Calls function when the event indicated by the dir parameter occurs in fd, a file descriptor.
Of the two types, EV_SELECT0 is the one you typically specify. EV_SELECT0 specifies that the handler should be invoked only when there are no outstanding push/pop contexts. You should use EV_SELECT0 when the callback uses the routines OMpush_ctx/OMpop_ctx. Otherwise, you can use EV_SELECT. EV_SELECT specifies that the handler can be called in the middle of a push/pop context, but in this case, it should not begin a new context.
- EV_PRE0 or EV_PRE- Calls function right before waiting for events. The fd and dir parameters have no meaning and should be set to 0.
Of the two types, EV_PRE0 is the one you typically specify. EV_PRE0 specifies that the handler should be invoked only when there are no outstanding push/pop contexts. You should use EV_PRE0 when the callback creates its own push/pop context. Otherwise, you can use EV_PRE. EV_PRE specifies that the handler can be called in the middle of a push/pop context.
- EV_POST- Calls function right after having waited for events. The fd and dir parameters have no meaning and should be set to 0.
- EV_POLL or EV_TIMEOUT - Calls function when there are no events. EV_POLL calls the function immediately. EV_TIMEOUT calls the function after a certain number of milliseconds, which you specify with the dir parameter. The fd parameter has no meaning and should be set to 0. For EV_POLL, the dir parameter has no meaning and should be set to 0.
EVdel_select deletes an event callback handler. The parameters to EVdel_select must match those of the EVadd_select that created the handler.
An event type, as described above:
EV_SELECT0
EV_SELECT
EV_PRE0
EV_PRE
EV_POST
EV_POLL
EV_TIMEOUTA file descriptor. fd has meaning only when type is EV_SELECT0 or EV_SELECT. Otherwise, it should be 0.
A pointer to a user-supplied callback function. The function should take a single pointer argument.
The fourth argument should be NULL.
The argument passed to function.
When the type is EV_SELECT0 or EV_SELECT, a further refinement of the event type:
When the type is EV_TIMEOUT, dir specifies the number of milliseconds to wait before invoking the event handler.
For other types, dir has no meaning and should be 0.
EVFlush_events flushes out pending window system expose events. It is particularly useful on UNIX systems since the Motif library uses window system expose events to refresh widgets after widget attributes have been changed. You may need to call this routine after you have performed an OMpop_ctx call that triggered a widget's update function. Even though the widget's update function was called, the display of the widget may not have been updated until all pending expose events are handled.
In this example, the OMpush_ctx and OMpop_ctx routines bracket an operation which changes a slider's value. The slider itself is not updated until after the EVflush_events call.
OMpush_ctx(my_obj_id, 0, 0, 0);
OMset_name_real_val(slider_id, OMstr_to_name("value"), 3.0);
OMpop_ctx(my_obj_id);
EVflush_events();
void EVXinit_display (disp);
void EVXadd_event_hndlr (disp, wind, mask, hndlr, udata, 0, NULL, NULL);
void EVXdel_event_hndlr (disp, wind, mask, hndlr, udata);
void EVXdel_events (disp, wind);
Display * disp;
Window wind;
unsigned int mask;
EVXhndlr hndlr;
void * udata;
These routines define callback handlers for X events (UNIX platforms only).
EVXinit_display initializes an X display. The routine must be called once per X display if you are using the routine EVXadd_event_hndlr.
EVXadd_event_hndlr adds an X event callback handler. When a set of X events occurs on an X window, the system will call the function you supply. The parameters specify the X display; window; event mask; callback function; and data argument for the callback function. The sixth parameter must be 0. The seventh and eighth parameters must be NULL.
EVXdel_event_hndlr deletes an X event callback handler. The parameters to EVXdel_event_hndlr must match the corresponding parameters of the EVXadd_event_hndlr that created the handler.
EVXdel_events deletes all X event callback handlers for a particular X-display window. If you have not deleted the handlers individually using EVXdel_event_hndlr, you should call EVXdel_events either closely before or closely after destroying a window. If you destroy a window without deleting the event handler, pending events in the X queue for this window may be delivered after the window is deleted causing intermittent X BadWindow errors.
A callback function. The function must have the following prototype:
void hndlr (Display * disp, Window wind, XEvent event, void * udata);
disp is an X display. wind is an X window. event is an X event. udata is the data argument specified by the udata parameter in EVXadd_event_hndlr.
The data argument passed to hndlr.
#include avs/f_utils.h
FILE *
FILEfopen(char *filename, char *type)
#include <avs/f_utils.h>
FILE *
FILEpath_fopen(char *filename, char *type, char *path, char sep)
#include <avs/f_utils.h>
char *
FILEfind(char *filename, char *path, char sep, int mode,
unsigned long *mod_time, int *path_index)
These routines provide file handling capabilities.
FILEfopen calls the standard fopen C library routine but will perform the following preprocessing on the filename argument:
- On unix machines, replaces \ characters with / characters.
- On MSDOS machines replaces / characters with \ characters.
- on both platforms, maps variable names specified with a prepended $ character. The definition of these variables are taken from standard system variables such as $XP_PATH<0>, $XP_PATH<1>, $MACHINE and any environment variables that you may have in your environment.
The return value contains the value returned by the fopen C library routine.
FILEpath_fopen opens the first file named filename found in a given list of directories specified by the path argument.Variables and directory separators in both the path and filename arguments are mapped as described for FILEfopen above.
FILEfind returns the absolute pathname of the file specified by filename in the specified path. The mode argument specifies permissions that this file must contain. The mod_time and path_index arguments optionally return the file modification time and an integer index specifying which directory was used to find the filename returned respectively.The return value is allocated with the malloc facility. You must call free when you are finished with this filename.
A pointer to a character string that contains the name of a file.
A character string. The initial portion of type must consist of one of the following character sequences (b character suffixes indicate binary file operation)
A pointer to a character string that contains a path specification. Directories in path are separated by the separator character sep.
A string containing the separator character (typically either ' ' or ':').
Integer specifying permissions that a file returned by FILEfind must contain. It should contain an or'd list of the flags:
Returns the modification time of the file found by FILEfind as returned by the stat system call. This argument can be specified as NULL if the return of this information is not desired.
Returns an integer index specifying which directory was used to find the filename returned by FILEfind. If the first directory is used, 0 is returned, if the second directotry is used, 1 is returned, and so on. If the filename argument itself was an absolute path, the path_index value of -1 is returned (that is, no directories in path were used to find the value in this case). This argument itself can be specified as NULL if you do not need this information.
OMadd_exit_func adds a callback function to be called when the process exits. The functions added with this mechanism are called in the reverse order in which they are added.
A pointer to a void function that is called with a single void * argument.
A void * argument that is passed to the func argument when the process exits.
OMadd_named_func adds a single entry to AVS/Express' internal table that maps functions to function identifiers.
If identifier already exists in the table, AVS/Express prints a warning message and replaces the existing entry.
This routine is used by code generated by AVS/Express to build this database. Users do not typically need to call this routine themselves.
/* Add a single entry to the function-identifier table. */
OMadd_named_func((OMpfi)add_num, OMstr_to_name("add numbers"));
OMadd_named_funcs adds several entries to AVS/Express' internal table that maps functions to function identifiers.
This internal table is constructed by code that AVS/Express generates. User code does not typically have to use this routine directly.
A set of function-to-identifier mappings.
The table should be defined as follows:
OMfunc_table table_name[] = {
{ (OMpfi)function, "identifier" },
{ (OMpfi)function, "identifier" };
...
};
If an identifier already exists in AVS/Express' internal table, AVS/Express prints a warning message and replaces the existing entry.
The number of entries in table_name.
/* Add a table of entries to the function-identifier table. */
static OMfunc_table user_funcs[] = {
{ (OMpfi)add_num, "add numbers" },
{ (OMpfi)subtract_num, "subtract numbers" }
};
...
OMadd_named_funcs(user_funcs,
(sizeof(usr_funcs)/sizeof(OMfunc_table)));
void OMadd_notify_req (
OMobj_id object_id,
OMobj_id template_id,
OMobj_id method_id,
OMobj_id argument_id,
unsigned int event_mask,
int mode );
void OMdel_notify_req (
OMobj_id object_id,
OMobj_id template_id,
OMobj_id method_id,
OMobj_id argument_id,
unsigned int event_mask,
int mode );
These routines add or delete a notification request. These routines are used by method objects to implement their callback functionality. You do not typically need to call them yourself.
The id of the object on which to place the notification request. That is, a notification request is to be generated when an event occurs in object_id.
The optional id of a template of subobjects on which to place the notification. See Example 2 below.
To indicate no object, specify OMnull_obj.
The id of the method object to be notified when the event occurs.
An optional object id to be passed to the invoked function.
To indicate no id, specify OMnull_obj.
The events that, when they occur in object_id, will cause a notification on the function.
a. Propagated means that the notification request extends to objects referenced in the object_id's value parameter, and to objects referenced by those objects, and so forth.
b. Queued means that if the notification is generated, it is added to AVS/Express' internal queue of notifications to process. Not queued means that AVS/Express processes the notifications immediately.
Options when adding notifications. mode is ignored in a call to OMdel_notify_req.
mode can be any of the following. You can OR together individual modes.
/* Notify myfunc_id when val1_id's property has changed.
Pass myfunc_id as an argument. */
OMobj_id myfunc_id, val1_id,my_arg;
...
OMadd_notify_req(val1_id, OMnull_obj, myfunc_id, my_arg,
OM_EVENT_PROP, 0);
Here is an example of using template_id.
The V code below defines group g3 as follows:
If you put a notification request on g3, by default a notification will be generated if any of g3's subobjects change, including subobjects a, b, c, and d.
To limit the notification to g3 and the subobjects inherited from g1, you can do the following:
OMobj_id myfunc_id, g3_id, g1_id, my_arg;
...
OMadd_notify_req(g3_id, g1_id, myfunc_id, may_arg,
OM_EVENT_VAL, 0);
int OMadd_obj_ref (
OMobj_id referencing_object,
OMobj_id referenced_object,
int mode );
int OMXobj::add_obj_ref(
OMobj_id referenced_object,
int mode = 0 );
OMadd_obj_ref makes a connection in referencing_object to referenced_object.
OMadd_obj_ref is useful for both single connections and arrays of connections. For an array of connections, call OMadd_obj_ref multiple times, specifying the same referencing object each time and a different referenced object.
An error occurs if the referencing object is a scalar that is already connected to an object.
To replace or remove an object reference, call OMset_obj_ref instead. You can also use OMset_obj_ref to connect an object to a single other object.
For making special types of connections, call OMlink_objs.
The mode argument can specify the value OM_OBJ_REF_QUERY to obtain a status code that indicates whether or not the connection will be valid without actually making the connection. For normal operation, specify 0 for the mode.
The status code (see Section 1.7, Return status [page 1-22]).
OMadd_subobj makes object an immediate subobject of parent.
Positionally, object becomes the last subobject in parent. To control object's placement in parent, use OMinsert_subobj instead.
After you move an object that may have connections to it (using OMdel_subobj and OMadd_subobj), you should update the references to this object using OMupd_name_refs.
The id of the parent object. parent must be an object that can have subobjects, such as SingleWindowApp, Applications, or a library, group, or macro object.
The id of the object being parented. object must not currently have a parent.
The status code (see Section 1.7, Return status [page 1-22]).
OMadd_to_refcnt increments object's reference count.
This routine is useful when you are storing the object in a way that is unknown to the Object Manager. It ensures that the object will not be deleted until you delete your reference. If you call OMadd_to_refcnt, you should decrement the refcnt when you are finished with object by calling OMdestroy_obj.
The second argument must be set to 1.
The status code (see Section 1.7, Return status [page 1-22]).
OMbegin_op and OMend_op suspend then subsequently resume execution of objects.
You use OMbegin_op and OMend_op in pairs:
OMbegin_op();
... /* Statements that update objects, such as
by making connections or setting values. */
OMend_op();
- OMbegin_op instructs the Object Manager to queue event notifications that subsequently occur. Consequently, objects do not execute.
- OMend_op delivers the queued notifications to the appropriate objects. The objects execute according to those notifications.
Calls to OMbegin_op and OMend_op can be nested. OMend_op delivers the notifications queued since the most recent call to OMbegin_op. It also removes those notifications from the queue.
OMend_op acts as a synchronization point. When OMend_op returns, all notifications queued since the most recent call to OMbegin_op will have been delivered and the objects will have finished executing.
OMbegin_op is generally easier to use than its lower-level alternative, OMpush_ctx, but is not as flexible. OMbegin_op and OMend_op are equivalent to the following calls to OMpush_ctx and OMpop_ctx:
OMchanged is normally called from a method's update function. It can be used to determine whether or not one of the parameters has changed since the last invocation of the method.
The id of one of the parameters to the object.
The sequence number of the method. This is passed as an argument to methods written with the omethod and cxxmethod method types.
Returns a 1 if the parameter has changed. Returns a 0 value otherwise.
Given this V code for a simple module
int
my_module_update(OMobj_id obj_id, OMevent_mask mask,
int seq_num)
{
OMobj_id param_id;
param_id = OMfind_subobj(obj_id,
OMstr_to_name("my_param1"),
OM_OBJ_RD);
if (OMchanged(param_id, seq_num)) { /* param1 changed */
...
}
...
OMclose_obj sets the instanced flag for an object and its subobjects so that the object may now execute.
For a discussion of using OMclose_obj, see the mode argument in Section 1.26, OMcopy_obj [page 1-52].
The id of an object. The object must be an instance, for example, an object in Applications or SingleWindowApp.
The status code (see Section 1.7, Return status [page 1-22]).
OMobj_id OMcopy_obj (
OMobj_id template,
OMobj_name newobj_name,
OMobj_id parent,
OMproc_id proc,
int mode );
OMcopy_obj is a low level routine that you can use to create a new object. It provides slightly more flexibility than the higher level routine OMcreate_obj_from_path in how the new object is named if there is already an existing object with that name. Normally, you should use OMcreate_obj_from_path.
OMcopy_obj creates an object whose type is template, a template object, and whose name is newobj_name. The object becomes an immediate subobject of parent. The object executes in the process specified by template or, if template has no process, the process indicated by proc. The close parameter indicates whether the object's instanced flag should be set.
To create an object whose type is a base type, such as group, macro, or int, call OMcreate_obj or OMcreate_obj_from_path instead.
If you specify OM_NULL_NAME, the Object Manager gives the new object the same name as class.
It is your responsibility to assure that the new object's name is unique within parent. If an object of the same name already exists in parent, the Object Manager replaces the existing object with the new one.
The routine OMget_uniq_name is useful for determining a unique name for an object.
By contrast, the routine OMcreate_obj_from_path assures that the new object has a unique name.
The id of the new object's parent. parent can be any object that can have subobjects, such as SingleWindowApp, Applications, or a library, group, or macro.
For parent you can specify OMnull_obj. The new object is created with no parent. You can subsequently assign it a parent with OMadd_subobj.
The default process id for the new object. The process id takes effect only if the class object does not specify a process.
Typically you specify OMlocal_proc_id, a predefined variable set to the id of the calling process.
Alternatively, you can call OMobj_proc to get the process id of a particular object.
A mode indicating whether to set the instanced flag for the object and its subobjects. mode applies only when creating an instance, for example, an object in Applications or SingleWindowApp. An instance executes only when its instanced flag is set.
The id of the new object; or OMnull_obj on an error.
OMobj_id OMcreate_obj (
OMobj_name newobj_name,
OMtype_id type,
OMobj_id parent,
OMnull_obj
OMproc_id proc );
This is a low-level routine for creating a new object from a base type. Most users should use the routine OMcreate_obj_from_path to create new objects. Only use this routine if there is no template object defined of the type you wish to create.
OMcreate_obj creates an object whose type is type, a primitive type such as group, macro, or int. The new object's name is newobj_name. The object becomes an immediate subobject of parent. The object executes in the process indicated by proc.
The new object's instanced flag is not set, even if the object is an instance. You can set the instanced flag explicitly with a call to OMclose_obj.
To create an object whose type is a class, call OMcopy_obj or OMcreate_obj_from_path instead.
If you specify OM_NULL_NAME, the Object Manager gives the new object the same name as class.
It is your responsibility to ensure that the new object's name is unique within parent. If an object of the same name already exists in parent, the Object Manager replaces the existing object with the new one.
The routine OMget_uniq_name is useful for determining a unique name for an object.
By contrast, the routine OMcreate_obj_from_path assures that the new object has a unique name.
The include file om_type.h defines the type variables you can specify for type, including the following common ones:
Alternatively, you can use the routine OMstr_to_type to return the type id corresponding to the type's string name.
The id of the new object's parent. parent can be any object that can have subobjects, such as SingleWindowApp, Applications, or a library, group, or macro.
For parent you can specify OMnull_obj. The new object is created with no parent. You can subsequently assign it a parent with OMadd_subobj.
The fourth argument must be OMnull_obj.
Typically you specify OMlocal_proc_id, a predefined variable set to the id of the calling process.
Alternatively, you can call OMobj_proc to get the process id of a particular object.
The id of the new object; OMnull_obj on an error.
OMcreate_obj_from_path creates an object from a template object. The template object can be any object in the Templates hierarchy. It is specified by a character string that represents the pathname to that object. The new object's name is newobj_name. The object becomes an immediate subobject of parent. The new object's default process id is the id of the calling process. If the new object is an instance, its instanced flag is set so that it will execute.
OMcreate_obj_from_path is generally easier to use than its lower-level alternatives, OMcopy_obj and OMcreate_obj.
The path name of a template object, specified as a string. Do not specify an instanced object.
You specify a name just as you would in V code. Typically, this means that you can specify an unqualified name. For example:
Depending on the object, you may need to specify a pathname if the library containing the object is not global. For example, the Data Visualization Kit's module objects require the prefix MODS:
The name of the new object, specified as a string. If you specify a null string, the Object Manager gives the new object the same name as type.
OMcreate_obj_from_path ensures that the resulting name is unique within the parent specified. If necessary, the routine makes the name unique by appending the string #n.
The id of the new object's parent. parent can be any object that can have subobjects, such as SingleWindowApp, Applications, or a library, group, or macro.
For parent you can specify OMnull_obj. The new object is created with no parent. You can subsequently assign it a parent with OMadd_subobj.
The id of the new object; or OMnull_obj on an error.
int OMdel_obj_ref (
OMobj_id referencing_object,
OMobj_id referenced_object,
0 );
int OMXobj::del_obj_ref (
OMobj_id referenced_object);
OMdel_obj_ref deletes a connection in referencing_object to referenced_object. This routine can be used, in particular, when deleting a single object reference from an object that has a list of references.
The status code (see Section 1.7, Return status [page 1-22]).
OMdel_subobj deletes an object from its parent. The object still exists, but it has no parent object.
The id of object's current parent.
The subobject being deleted from parent.
The status code (see Section 1.7, Return status [page 1-22]).
OMdestroy_objis a low level routine used for destroying objects. Normally, users use the routine OMuser_destroy_obj to destroy an object. This routine does not remove connections to this object and therefore only destroys the object when the last connection is deleted.
OMdestroy_obj decrements an object's reference count. If the reference count is 0, it also deletes the object. Depending on the mode argument, it may also call OMdel_subobj to remove the object from the parent's subobject list.
The Object Manager maintains a reference count for each object, indicating the extent to which the object is in use. For example, you create an object, either in V or with a routine such as OMcreate_obj. The object's reference count is 1. If another object connects to the object, the object's reference count is incremented. If the connection to the object is removed, the object's reference count is decremented. An object's reference count can be incremented explicitly with a call to OMadd_to_refcnt. If the object's reference count is 0, which can happen only on a call to OMdestroy_obj, the object is deleted.
The id of the object being deleted.
A mode indicating whether the routine should call OMdel_subobj after decrementing the object's reference count. If called, OMdel_subobj removes the object from its parent so that the object now has a null parent id.
- 0 - Call OMdel_subobj only if the reference count is decremented to 0.
- OM_DESTROY_CHILD - Do not call OMdel_subobj, regardless of the reference count. This flag should not be used by users of this routine. It is used by the parent object itself when it destroys its list of subobjects explicitly.
- OM_DESTROY_SUBOBJ - Call OMdel_subobj, regardless of the reference count. You should use this flag if you want the object deleted from the object hierarchy regardless of whether or not it is actually deleted. This removes the object from the Network Editor if it is currently being displayed. You should use this flag if you are deleting this object on behalf of the user of the object. Otherwise, the user might be able to delete the object again using the Network Editor or VCP.
0 if the reference count is greater than 0 after being decremented; 1 if the reference count is 0 after being decremented; -1 if an error has occurred, regardless of the reference count.
void OMedit_obj(
OMobj_id object_id);
void OMedit_root_obj();
void OMedit_obj_ptr(
int elem_id,
int proc_id);
These routines invoke the V command processor on the object specified. They are particularly useful when called from the debugger to help you debug your program. The variants of these routines help overcome the limitations that various debuggers have.
The routine OMedit_root_obj brings up the VCP on the Root object. Since it takes no arguments, it can be called from most debuggers.
The routine OMedit_obj_ptr is useful when your debugger prohibits you from passing structures as arguments to functions. The OMobj_id structure consists of two members: elem_id and proc_id. The elem_id member is passed as the first argument to the function, the proc_id is passed as the second. You call this routine from the debugger like:
Once you are finished with the VCP, you can return to debugging your program by closing all open objects and entering the EOF character on your system (often Ctrl-d).
OMequal_objs compares two object ids.
The returned value indicates whether the object ids are the same:
/* Compare two object ids. */
OMobj_id object1_id, object2_id;
...
if (OMequal_objs(object1_id, object2_id) == 1)
printf("Object ids are equal.\n");
else
printf("Object ids are not equal or an error has occurred.\n");
OMexit exits the currently executing process using the exit system call. If you want to cause the main process to exit from an external process, see OMprocess_exit.
An exit status for this process to pass to the exit system call.
OMfind_str_subobj returns the id of any subobject of ancestor. subobject_path is the object's V pathname relative to ancestor. The mode parameter indicates how the process intends to use the object.
The id of an ancestor (parent, grandparent, etc.) of the object you are seeking.
The relative V pathname of the object you are seeking, specified as a character string. This pathname string can contain the <- characters to go up in the hierarchy and can contain simple array dimension specification to go through array values.
A mode indicating how the process intends to use the object:
The id of the found object; or OMnull_obj on an error.
the following are valid calls to OMfind_str_subobj. Assume grp1_id contains grp1's object id:
var1_id = OMfind_str_subobj (grp1_id, "var1", OM_OBJ_RW);
var2_id = OMfind_str_subobj (grp1_id, "grp2.var2",
OM_OBJ_RW);
You can use this call to access a subobject of an array of groups. Given the V code
If you have the id of the object grp3 in variable grp3_id, you can get id of the subobject a in the 0'th element in the array using the call:
You can go up the hierarchy using the <- operator. Given the V code
If you have the id of sub_grp1 in the variable sub_grp1_id, you can get the object id of the b subobject with
OMobj_id OMfind_subobj (
OMobj_id parent_id,
OMobj_name search_name,
int mode );
OMobj_id OMlookup_subobj (
OMobj_id parent_id,
OMobj_name search_name,
int mode );
OMobj_id OMfind_obj (
OMobj_id object_id,
OMobj_name search_name,
int mode );
These routines search for an object, which you specify by name, and return the object's id.
The routines differ in the scope of their search.
These routines extend their search beyond the scope described above when they encounter a global library object as a subobject. In this case, they will search through the subobjects of the global library as well. This functionality can be disabled by OR'ing in the flag OM_FIND_NO_LIBRARIES into the mode argument.
An object id. The search is performed in the context of this object.
The unqualified name of the object to find.
Indication of how the process intends to use the object.
Consider the following V code:
When g1 is created, AVS/Express does not immediately create its subobjects. Rather, for each subobject, AVS/Express waits until the subobject is actually referenced, for example, a value is assigned to it.
If mode is OM_OBJ_RD and the subobject has not yet been created, AVS/Express returns instead the id of the template subobject, in this example, g.a. This works provided the program intends only to read the object.
If mode is OM_OBJ_RW, AVS/Express always returns the id of the subobject, in this example, g1.a. If the subobject does not yet exist, AVS/Express creates it.
Optionally, you can OR into the mode parameter additional flags to qualify the object search.
The returned value is either the found object's id or, if OMfind_obj failed, OMnull_obj(see Section 1.7, Return status [page 1-22]).
/* Find subobject x. Its parent's id is grp1_id. */
OMobj_id grp1_id, x_id;
...
x_id = OMfind_subobj(grp1_id, OMstr_to_name("x"),
OM_OBJ_RD);
if OMis_null_obj(x_id)
printf("Error searching for x\n");
/* Find object x in the context of the object whose id
is grp1_id. */
OMobj_id grp1_id, x_id;
...
x_id = OMfind_obj(grp1_id, OMstr_to_name("x"), OM_OBJ_RD);
if (OMis_null_obj(x_id))
printf("Error searching for x\n");
OMfunc_to_name queries AVS/Express' internal table that maps functions to function identifiers, and returns the identifier corresponding to a specified function.
/* Return the identifier corresponding to function add_num. */
OMobj_name function_identifier;
...
function_identifier = OMfunc_to_name((OMpfi)add_num);
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 );
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 Section 1.43, OMget_array_val, OMset_array_val, OMdel_array_val [page 1-89]. For details of the calls appropriate for handling arrays of strings, please see Section 1.63, OMget_str_array_val and OMset_str_array_val [page 1-129]
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.
1. Depending on mode, array_ptr, and whether the array is local to the calling process, AVS/Express does one of the following:
2. 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.
3. 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:
As an output argument, indicates the array's type. AVS/Express provides the following symbolic constants, defined in <avs/om.h>:
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.
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.
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.
The mode, indicating how the program intends to use the array.
For details on the different modes, see the table below.
The status code (see Section 1.7, Return status [page 1-22]).
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).
/* 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, (char *) &array_type, &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);
OMget_array_dims returns the dimensions of the specified object.
An output argument, set to the number of dimensions in the array.
An array output argument indicating the size in each dimension. The first element of the array is set to fastest varying dimension which is the size of the rightmost dimension, and so forth.
size_of_each_dimension 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.
If you do not care about each dimensions's size, you can set size_of_each_dimension to NULL.
The status code (see Section 1.7, Return status [page 1-22]).
Assume you have an integer array object defined as follows in the V code:
You can then query the array's dimensions and size in each dimension. In the code below, assume that parent_id contains the id of my_array's parent object:
OMobj_id parent_id, my_array;
int i, ndims;
int dim_sizes[OM_ARRAY_MAXDIM];
...
my_array = OMfind_subobj(parent_id,
OMstr_to_name("my_array"),
OM_OBJ_RD);
status = OMget_array_dims(my_array, &ndims, &dim_sizes);
if (status == 1) {
printf("Number of dimensions: %d\n", ndims);
printf("Dimensions: ");
for (i=0; i<ndims; i++)
printf("[%d]", dim_sizes[i]);
printf("\n");
};
OMget_array_ref is used in conjunction with OMget_num_refs to access an objects list of connections as an array. The object specified can be any object that has connections but if the object is not an array object, the ref_index parameter must always be 0.
The id of an object. The object can be any object that has connections currently.
An array value. AVS/Express uses 0-based indexing; i.e., the index of the first connection in an array is 0.
The id of the specified connection is returned.
This argument is typically supplied with 0 but the constant OM_REF_SYMBOLIC can be used to obtain the id of a subobject of a by-reference group instead of the id of the subobject of the by-referenced group's value. This is the value that the Network Editor uses to display hierarchical connections properly.
A status code. See Section 1.7, Return status [page 1-22].
group a, b, c;
group &grp1[] => {a, b, c};and with grp1's object_id in grp1_id, the C code can be used to access the object ids of a, b, and c.
OMobj_id grp1_id, ref_id;
int i, num_refs;
grp1_id = ...
if (OMget_num_refs(grp1_id, &num_refs) != 1) num_refs = 0;
for (i = 0; i < num_refs; i++) {
if (OMget_array_ref(grp1_id, i, &ref_id, 0) != 1)
continue;
printf("object is: %s\n",OMret_obj_name(ref_id));
};
int OMget_array_size (
OMobj_id object_id,
int *size );
int OMXobj::get_array_size (
int *size );
int OMset_array_size (
OMobj_id object_id,
int size );
These routines get and set the size of the specified array object.
OMset_array_size is suitable only for one-dimensional arrays. To set the dimensions of multi-dimensional arrays, define the dimensions of your object in terms of integer AVS/Express objects and set the values of these objects directly.
In OMget_array_size, an output argument containing the array size. For a multi-dimensional array, OMget_array_size returns the product of the sizes in each dimension.
In OMset_array_size, an input argument specifying the new array size.
The status code (see Section 1.7, Return status [page 1-22]).
Assume you have integer array objects defined as follows in the V code:
my_array1 is a multidimensional array, so you cannot set its size with this routine. To get the values of each dimension independently, use: OMget_array_dims. To set the values of each dimension independently, you set the values of the mdims and ndims objects using OMset_int_val.
my_array2 is one-dimensional, so you can get and set its size with these routines. In the code below, assume that parent_id contains the id of the arrays' parent object:
OMobj_id parent_id, my_array1, my_array2;
int size;
int dim_sizes[OM_ARRAY_MAXDIM];
...
my_array1 = OMfind_subobj(parent_id,
OMstr_to_name("my_array1"),
OM_OBJ_RD);
my_array2 = OMfind_subobj(parent_id,
OMstr_to_name("my_array2"),
OM_OBJ_RW);
status = OMget_array_size(my_array1, &size);
printf("Array size: %d", size) /* Prints 20000. */
status = OMget_array_size(my_array2, &size);
printf("Array size: %d", size) /* Prints 100. */
status = OMset_array_size(my_array2, 300);
int OMget_array_subobj (
OMobj_id object_id,
int subobject_index,
OMobj_id *subobject_id,
int mode );
OMget_array_subobj treats the immediate subobjects of object_id as an array of objects and returns the id of the specified subobject. You identify the subobject in terms of its index into the array. Use this routine in conjunction with the routine OMget_num_subobjs to traverse the list of subobjects of a hierarchical object.
The id of an object with subobjects.
The index of a subobject. AVS/Express uses 0-based indexing; i.e., the index of the first subobject is 0.
An output argument, set to the id of the requested subobject.
The access mode indicating how the calling process intends to use the subobject:
Consider the following V code:
When g1 is created, AVS/Express does not immediately create its subobjects. Rather, for each subobject, AVS/Express waits until the subobject is actually referenced, for example, when a value is assigned to it.
If mode is OM_OBJ_RD and the subobject has not yet been created, AVS/Express returns instead the id of the template subobject, in this example, g.a. This works provided the program intends only to read the object.
If mode is OM_OBJ_RW, AVS/Express always returns the id of the subobject, in this example, g1.a. If the subobject does not yet exist, AVS/Express creates it.
The status code (see Section 1.7, Return status [page 1-22]).
the following C statements return the ids of the subobjects. Assume grp1_id is set to the id of object grp1:
OMobj_id grp1_id, subobjs[10];
int i;
int num;
int status;
...
status = OMget_num_subobjs (grp1_id, &num);
for (i=0; i < num; i++)
status = OMget_array_subobj(grp1_id, i, &subobjs[i],
OM_OBJ_RD);
int OMget_array_val (
OMobj_id object_id,
int value_index,
OMobj_id *value_id,
int mode );
int OMset_array_val (
OMobj_id object_id,
int value_index,
OMobj_id value_id );
int OMdel_array_val (
OMobj_id object_id,
OMobj_id value_id );
These routines get, set, or delete an object id in a one-dimensional array of groups, modules or macros.
The object is either an array of pointers/references to other objects or a by-value group array.
In some cases, the OMget_array_val routine returns the OMobj_id of a link object and not the end value in and of itself. It is a good practice to use the routine OMget_obj_val, OMget_obj_pval, and OMset_obj_val on the return value from OMget_array_val and to check the status return of that routine. This problem occurs in the following V definition:
The OMget_array_val routine will return the id of v1 which does not have a valid value at this time. The call OMget_obj_val returns 0 in this case.
OMset_array_val only works when the array object's reference mode is by-reference or by-pointer, not by-value. It has two different behaviors depending upon whether the dimensions of the array are explicitly defined or not defined. If the V definition of the object looks like
the OMset_array_val call inserts the new value into the array at the specified location, moving forward the contents of the array, and increasing the array's size by one. If you specify the value_index parameter with the constant OM_ARRAY_APPEND, a new value is added onto the end of the array.
If the V definition looks like
the OMset_array_val call replaces the object specified index with the object value specified with the value_id parameter.
OMdel_array_val deletes an object's reference to another object, but does not delete that other object. You can use OMdel_array_val when the object's mode is by-reference or by-pointer, but not when its mode is by-value.
The id of an object. The object must be a one-dimensional array of pointers (* mode) or references (& mode) to other objects.
An array value. AVS/Express uses 0-based indexing; i.e., the index of the first value in an array is 0.
In OMset_array_val, index can be OM_ARRAY_APPEND, meaning that the object should be added to the end of the array.
In OMget_array_val, the id of the specified object.
In OMset_array_val, the id of the object to place into the array.
In OMdel_array_val, the id of the object to be deleted from the array.
In a call to OMget_array_val, the access mode indicating how the process intends to use the subobject:
Consider the following V code:
When coordinates is created, AVS/Express does not immediately create all four occurrences of it. Rather, AVS/Express creates a template copy of the group, then, for each occurrence, waits until the occurrence is actually referenced, for example, when a value is assigned to one of its subobjects.
If mode is OM_OBJ_RD and the occurrence has not yet been created, AVS/Express returns instead the id of the template occurrence. This works provided the program intends only to read the object.
If mode is OM_OBJ_RW, AVS/Express always returns the id of the occurrence. If the occurrence does not yet exist, AVS/Express creates it.
A status code. See Section 1.7, Return status [page 1-22].
A V file contains the following definitions:
The following code illustrates how you can modify the values in my_images:
OMobj_id a_id, b_id, c_id, d_id, e_id, my_images_id;
OMobj_id parent_object;
OMobj_id returned_id;
int status;
...
/* Get the object ids of the images. */
a_id = OMfind_subobj(parent_object, OMstr_to_name("a"),
OM_OBJ_RD);
... /* Same for the other objects. The mode for my_images_id is
OM_OBJ_RW. */
/* Get the object id of the first value in my_images. */
status = OMget_array_val(my_images_id, 0, &returned_id,
OM_OBJ_RD);
/* Set the second value in my_images to object d. */
status = OMset_array_val(my_images_id, 1, d_id);
/* Add object e to the end of my_images. */
status = OMset_array_val(my_images_id, OM_ARRAY_APPEND, e_id);
/* Delete object c from my_images. */
status = OMdel_array_val(my_imdages_id, c_id);
OMget_cur_seq returns the current sequence number. When an object's value is changed, its sequence number is updated with the current sequence number. This sequence number is used until the next call to OMpush_ctx or OMpop_ctx.
The id of any object in the application.
The sequence number or an error status code (see Section 1.7, Return status [page 1-22]).
int OMget_data_type (
OMobj_id object_id,
int *data_type );
int OMset_data_type (
OMobj_id object_id,
int data_type );
OMget_data_type gets an object's data type.
OMset_data_type sets an objects' data type. This routine is used to convert an object defined as type prim into an object of type int, float, etc.
For OMget_data_type, an output argument containing the object's data type.
For OMset_data_type an input argument defining the objects' new type.
data_type specifies the integer code for the data type. AVS/Express provides the following symbolic constants, defined in <avs/om.h>:
The status code (see Section 1.7, Return status [page 1-22]).
/* Get object var1_id's data type and call the
appropriate routine to process the variable. */
OMobj_id var1_id;
int status;
int var1_data_type;
...
status = OMget_data_type(var1_id, &var1_data_type);
if(var1_data_type == OM_TYPE_INT)
process_integer(var1_id);
int OMget_func_val (
OMobj_id object_id,
OMpfi *function );
int OMset_func_val (
OMobj_id object_id,
OMpfi function );
These routines get and set a method object's function pointer; i.e., the function that is executed when the method is invoked.
The status code (see Section 1.7, Return status [page 1-22]).
/* Set the function called by my_func_id (the object id
of a method). */
OMobj_id my_func_id;
int status;
...
status = OMset_func_val(my_func_id, (OMpfi) add_vals);
int OMget_iarray_val (OMobj_id object_id, int index, int *ivalue );
int OMget_rarray_val (OMobj_id object_id, int index, double *rvalue );;
These routines get a single element in an array object. These routines are suitable only for one-dimensional arrays. See the documentation for OMget_sub_barray and OMset_sub_barray for a more general routine that operates on multi-dimensional arrays.
The routines operate on different types of arrays.
The id of an object. The object must be a one-dimensional array.
The index of the value to retrieve. AVS/Express uses 0-based indexing; i.e., the index of the first value in an array is 0.
An output argument containing the requested array value.
The status code (see Section 1.7, Return status [page 1-22]).
The V file below defines a one-dimensional array:
The following code segment gets the second element:
int OMget_int_val (
OMobj_id object_id,
int *value );
int OMset_int_val (
OMobj_id object_id,
int value );
int OMget_name_int_val (
OMobj_id object_id,
OMobj_name subobject_name,
int *value );
int OMset_name_int_val (
OMobj_id object_id,
OMobj_name subobject_name,
int value );
int OMXobj::get_int_val(
int *value );
int OMXobj::set_int_val(
int value );
These routines get and set an integer object's value.
The routines access the target object in different ways.
The name of one of object_id's immediate subobjects.
In OMget_int_val and OMget_name_int_val, an output argument containing the object's value.
In OMset_int_val and OMset_name_int_val, an input argument specifying the new value.
The status code (see Section 1.7, Return status [page 1-22]).
/* Get and set object var1_id's value. */
OMobj_id var1_id;
int status;
int var1_value;
...
status = OMget_int_val(var1_id, &var1_value);
if (status == 1) {
var1_value *= 2;
status = OMset_int_val(var1_id, var1_value);
}
/* Get the value of object x, an integer subobject of
grp1_id. */
OMobj_id grp1_id;
int status;
int x_value;
...
status = OMget_name_int_val(var1_id, OMstr_to_name("x"),
&x_value);
OMget_num_subobjs returns the number of subobjects in the specified object.
An output argument, set to the number of subobjects.
The status code (see Section 1.7, Return status [page 1-22]).
the following C statements return the ids of the subobjects. Assume grp1_id is set to the id of object grp1:
OMobj_id grp1_id, subobjs[10];
int i;
int num;
int status;
...
status = OMget_num_subobjs (grp1_id, &num);
for (i=0; i < num; i++)
status = OMget_array_subobj(grp1_id, i, &subobjs[i],
OM_OBJ_RD);
OMget_num_refs returns the number of connections for the specified object.
An output argument, set to the number of connections.
The status code (see Section 1.7, Return status [page 1-22]).
int OMget_obj_att (
OMobj_id object_id,
OMobj_name attribute,
int *state );
int OMset_obj_att (
OMobj_id object_id,
OMobj_name attribute,
int state );
These routines get and set an object's attribute.
The name of an attribute. You can specify any of the following variables, which are defined in <avs/om_att.h>:
In OMget_obj_att, an output argument containing the attribute's state.
In OMset_obj_att, an input argument specifying the new state.
The state is one of the following:
The status code (see Section 1.7, Return status [page 1-22]).
/* Flip object grp1_id's notify state. */
#include <avs/OM_att.h>
OMobj_id grp1_id;
int state;
int status;
...
status = OMget_obj_att(grp1_id, OM_att_notify, &state);
state = !state;
status = OMset_obj_att(grp1_id, OM_att_notify, state);
int OMget_obj_name (
OMobj_id object_id,
OMobj_name *object_name );
int OMset_obj_name (
OMobj_id object_id,
OMobj_name object_name );
These routines get and set an object's name.
After you have changed an object's name, if this object may have any connections to it or to any of its subobjects, you should update these references by calling the routine OMupd_name_refs.
In OMget_obj_name, an output argument containing the object's name.
In OMset_obj_name, an input argument specifying the new object name.
The status code (see Section 1.7, Return status [page 1-22]).
/* Get object var1_id's name. */
OMobj_id var1_id;
int status;
OMobj_name var1_name;
...
status = OMget_obj_name(var1_id, &var1_name);
OMget_obj_parent gets the id of an object's parent.
An output argument containing the parent's id.
parent_id is set to OMnull_obj(an object id predefined in <avs/om.h>) if the object has no parent.
The status code (see Section 1.7, Return status [page 1-22]).
/* Get object var1_id's parent. */
OMobj_id var1_id;
int status;
OMobj_id var1_parent;
...
status = OMget_obj_parent(var1_id, &var1_parent);
if (OMequal_objs(var1_parent, OMnull_obj)
printf("Object has no parent\n");
OMobj_id OMget_obj_prop (object_id, property, 0 );
int OMget_obj_iprop (object_id, property, int *ival);
int OMget_obj_rprop (object_id, property, double *rval);
int OMget_obj_sprop (object_id, property, char **sval, maxlen);
int OMset_obj_iprop (object_id, property, int ival);
int OMset_obj_rprop (object_id, property, double rval);
int OMset_obj_sprop (object_id, property, char *sval);
OMobj_id object_id;
OMobj_name property;
These routines get and set an object's property.
OMget_obj_prop gets the id of a property. You can then call OMget_data_type to determine the property's data type, then OMget_obj_val and OMset_obj_val to get and set the property's value.
Alternatively, you can call one of the other routines, which combine these operations for particular data types.
AVS/Express-supplied properties, such as NEx and struct_name, have predefined names. The Network Editor names are defined in <avs/ne_om.h>. The OM names are defined in <avs/om_att.h> and <avs/om_type.h>.
Here are some commonly referenced property names and their data types. AVS/Express performs numeric data-type conversion, so, for example, you could refer to NE_name_NEheight in a call to OMget_obj_iprop even though it is defined to have a real value.
In one of the get routines, an output argument containing the property's value.
In one of the set routines, an input argument specifying the property's new value.
This value is passed to either OMget_str_val or OMset_str_val.
If you are using OMget_obj_prob, sval is an output argument containing the string. AVS/Express either allocates space for the string or places the array in an address you specify:
If you are using OMset_obj_prob, sval is an input argument specifying the address of the new value.
This parameter applies to OMget_obj_prob only. It is integer that is passed to OMget_str_val, and it indicates the maximum number of bytes to get. This argument is ignored if sval is a NULL pointer.
The status code (see Section 1.7, Return status [page 1-22]).
/* Get object var1_id's coordinates. */
OMobj_id var1_id;
int status;
int var1_x, var1_y;
...
status = OMget_obj_iprop(var1_id, NE_name_NEx, &var1_x);
status = OMget_obj_iprop(var1_id, NE_name_NEy, &var1_y);
int OMget_obj_ref_mode (
OMobj_id object_id,
int *reference_mode );
int OMset_obj_ref_mode (
OMobj_id object_id,
int reference_mode );
These routines get and set an object's reference mode.
In OMget_obj_ref_mode, an output argument containing the object's reference mode.
In OMset_obj_ref_mode, an input argument specifying the new mode.
reference_mode specifies the integer code for the mode. AVS/Express provides the following symbolic constants, defined in <avs/om.h>:
The status code (see Section 1.7, Return status [page 1-22]).
/* Get object var1_id's reference mode. */
OMobj_id var1_id;
int status;
int var1_ref_mode;
...
status = OMget_obj_ref_mode(var1_id, &var1_ref_mode);
OMget_obj_seq returns the sequence number of an object.
The optional id of a template object.
template_id is useful when object_id refers to an object with subobjects and the mode is OM_SEQ_SUBOBJS. See mode, below.
Typically, you set template_id to OMnull_obj to indicate no template.
Indicates how the sequence number is obtained:
The sequence number, or an error status code (see Section 1.7, Return status [page 1-22]).
The V code below defines a group object:
You can determine the highest sequence number among grp1, any of its subobjects, and any objects along subobject b's chain of references:
This example illustrates the use of template_id.
The V code below defines two groups:
Group g2 has four subobjects: c, d, and the two objects it inherited from g1, a, and b.
The following code segment determines the largest sequence number among group g2and its subobjects, but only considers subobjects a and b:
int OMget_obj_val (OMobj_id object_id, OMobj_id *value_id);
int OMget_obj_pval (OMobj_id object_id, OMobj_id *value_id, int mode);
int OMget_obj_ref (OMobj_id object_id, OMobj_id *value_id, int mode);
int OMset_obj_val (OMobj_id object_id, OMobj_id value_id, int mode);
These routines get or set a pointer or reference object's value. You use these routines when an object's mode is by-reference or by-pointer, to determine the pointed-to object.
The OMget_obj_xxx routines differ in the id they return. The examples in the table below refer to the following sample V code:
OMset_obj_val sets the value of object_id to the value defined by value_id. This is equivalent to the '=' operator in V. This is a one-time assignment, not a connection. If you have defined two objects in V:
the results are the same as declaring (in V):
For group objects that are not references or pointers, the OMset_obj_val call will be performed on subobjects with corresponding names in the two groups.
You can also use OMset_obj_val to unset an object's value by setting the value_id argument to OMnull_obj. For example, if you have an object defined in V:
For OMget_obj_val, OMget_obj_pval, and OMget_obj_ref, the id of the returned value. For OMset_obj_val, the id of the value that you want object_id to take.
Reserved for future use. Set to 0 in all cases.
The status code (see Section 1.7, Return status [page 1-22]).
/* Get the value pointed to by var1_id. AVS/Express
returns the id
of the object at the end of the chain. */
OMobj_id var1_id;
int status;
OMobj_id var1_value_id;
...
status = OMget_obj_val(var1_id, &var1_value_id);
char *OMget_path(
int which);
char *OMget_path_index(
int which,
int path_index,
char *buffer);
int OMget_num_paths(
int which);
These routines provide access to the path variables of the current AVS/Express session. The different paths defined by the system are:
The path this operation works on as defined by one of the constants above (e.g., OM_PATH).
The path returned. This number should be a value between 0 and the value returned by OMget_num_paths.
This specifies a piece of memory that the routine OMget_path_index uses to store the returned path. This buffer should be defined to be large enough to contain the maximum length path name for the machine. The AVS_PATH_MAX constant can be used for this purpose.
OMget_path returns a read-only character string that contains the list of directories in the specified path. The paths are separated by a space character. You should not free or modify the memory returned.
OMget_num_paths returns the number of directories in the specified path.
OMget_path_index copies the specified directory name into the buffer you specified and returns a pointer to that buffer.
This routine returns the list of ports for object_id. A subobject is placed in the list of ports returned if it has the NEportLevels or exported property set to a value greater than or equal to the number of levels down in the hierarchy it is removed from object_id.
The object whose ports are returned.
The number of ports in object_id.
An array of the object ids of the ports in object_id. If the num_ports value is greater than 0, you should free this array when you are finished with it using the C library routine free.
A value of 0 allows this object to be included in its own list of ports if it has the NEportLevels or exported property set to 1 or greater. A value OM_PORTS_NO_TOP_LEVEL prevents this object from being included in its own list of ports.
The status code (see Section 1.7, Return status [page 1-22]).
int OMget_ptr_val (
OMobj_id object_id,
void **value,
0 );
int OMset_ptr_val (
OMobj_id object_id,
void *value
0 );
int OMget_name_ptr_val (
OMobj_id parent_id,
OMobj_name object_name,
void **value,
0 );
int OMset_name_ptr_val (
OMobj_id parent_id,
OMobj_name object_name,
void *value
0 );
These routines get and set a pointer object's value. AVS/Express does not perform any manipulation on the pointer provided. It will not free the pointer when the object is destroyed. If your pointer was allocated with malloc, you will have to free it yourself when the object is destroyed with a method that is executed when the deinstanced event occurs.
The caller must be in the same process as the object for this routine to work. A -1 status is returned if the OMget_ptr_val or OMset_ptr_val routines are used with an object that is not in the same process.
In OMget_ptr_val, an output argument containing the object's value.
In OMset_int_val, an input argument specifying the new value.
The mode argument for the OMget_ptr_val and OMset_ptr_val routines is always passed as 0.
The status code (see Section 1.7, Return status [page 1-22]).
this C code can be used to store the pointer to a structure in the object my_id:
OMobj_id my_id;
int status;
my_id = ...
my_struct *ptr = (my_struct *)malloc(sizeof(my_struct));
...
status = OMset_ptr_val(my_id, (void *)ptr, 0);
This code can be used to retrieve the value later:
int OMget_real_val (
OMobj_id object_id,
double *value );
int OMset_real_val (
OMobj_id object_id,
double value );
int OMget_name_real_val (
OMobj_id object_id,
OMobj_name subobject_name,
double *value );
int OMset_name_real_val (
OMobj_id object_id,
OMobj_name subobject_name,
double value );
int OMXobj::get_real_val(
double *value );
int OMXobj::set_real_val(
double value );
These routines get and set a floating-point object's value.
The routines access the target object in different ways.
In a get routine, if the object's value parameter is a connection or expression, AVS/Express resolves it and returns the result.
The name of one of object_id's immediate subobjects.
In OMget_real_val and OMget_name_real_val, an output argument containing the object's value.
In OMset_real_val and OMset_name_real_val, an input argument specifying the new value.
The status code (see Section 1.7, Return status [page 1-22]).
/* Get and set object var1_id's value. */
OMobj_id var1_id;
int status;
double var1_value;
...
status = OMget_real_val(var1_id, &var1_value);
if (status == 1) {
var1_value *= 2;
status = OMset_real_val(var1_id, var1_value);
}
/* Get the value of object x, a floating-point subobject of
grp1_id. */
OMobj_id grp1_id;
int status;
double x_value;
...
status = OMget_name_real_val(var1_id, OMstr_to_name("x"),
&x_value);
This routine returns the list of objects that are connected to the object specified by object_id. This goes in the opposite direction from the OMget_num_refs and OMget_array_refs routines.
The id of the object whose connections are returned.
The number of connections to this object.
A pointer to an array of object ids that are connected to this object. This list is allocated with the C malloc call and must be freed by you when you are done with the list.
The mode in which this routine performs this operation:
A status code. See Section 1.7, Return status [page 1-22].
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,
char *value );
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:
The id of an object. The object must be a one-dimensional array of strings.
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.
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:
In OMset_str_array_val, value is an input argument specifying the address of the new string.
In OMget_str_array_str_val, the maximum number of characters to get. This argument is ignored if value is a NULL pointer.
A status code. See Section 1.7, Return status [page 1-22].
The following V code defines an array of strings:
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);
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. */
int OMget_str_val (
OMobj_id object_id,
char **value,
int maximum_size );
int OMget_str_val_mode (
OMobj_id object_id,
char **value,
int maximum_size,
int mode );
int OMset_str_val (
OMobj_id object_id,
char *value );
int OMget_name_str_val (
OMobj_id parent_id,
OMobj_name subobject_name,
char **value,
int maximum_size );
int OMset_name_str_val (
OMobj_id parent_id,
OMobj_name subobject_name,
char *value );
These routines get and set a string object's value.
In OMset_str_val, the value that is changed depends on the target object's reference mode:
a call to OMset_str_val on object px2 changes x's value.
By default when you call OMget_str_val, it attempts to translate the string using any installed dictionaries. You prevent this translation from occuring by calling the routine OMget_str_val_mode with the mode argument set to the flag OM_STR_NO_I18N.
In OMget_str_val, an output argument containing the string. AVS/Express either allocates space for the string or places the array in an address you specify:
In OMset_str_val, value is an input argument specifying the address of the new value.
In OMget_str_val, the maximum number of bytes to get. This argument is ignored if value is a NULL pointer.
For OMget_str_val_mode only, specifies the translation mode. A 0 argument indicates that translation should take place, a value of OM_STR_NO_I18N indicates that no translation should take place.
The status code (see Section 1.7, Return status [page 1-22]).
/* Get a string. OMget_str_val allocates space. */
OMobj_id str1_id;
int status;
char *str1_val = NULL;
...
status = OMget_str_val(str1_id, &str1_val, 0);
... /* Process the string. */
if (str1_val != NULL) free(str1_val);
/* 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_val(str1_id, &str1_ptr,
sizeof(str1_buf));
/* Process the string. No need to free the string. */
int OMget_sub_barray (object_id, ndim, size, min, max, bvalue);
int OMget_sub_sarray (object_id, ndim, size, min, max, svalue);
int OMget_sub_iarray (object_id, ndim, size, min, max, ivalue);
int OMget_sub_farray (object_id, ndim, size, min, max, fvalue);
int OMget_sub_rarray (object_id, ndim, size, min, max, rvalue);
int OMset_sub_barray (object_id, ndim, size, min, max, bvalue);
int OMset_sub_sarray (object_id, ndim, size, min, max, svalue);
int OMset_sub_iarray (object_id, ndim, size, min, max, ivalue);
int OMset_sub_farray (object_id, ndim, size, min, max, fvalue);
int OMset_sub_rarray (object_id, ndim, size, min, max, rvalue);
OMobj_id object_id;
int ndim, *size, *min, *max;
unsigned char *bvalue;
short *svalue;
int *ivalue;
float *fvalue;
double *rvalue;
These routines get and set a subarray of an array object. With the ndim and size parameters, you specify the number of dimensions in the array and the size of each dimension. With the min and max parameters, you specify the range to retrieve or set in each dimension.
The routines get different types of arrays.
The number of dimensions in the array object.
An array specifying the size of each dimension of the array object. The first value in this array is the fastest varying dimension in the array. This is the value that is the rightmost in the V specification for the dimensions.
Arrays specifying, respectively, the minimum and maximum indices to retrieve/set in each dimension of the array. The first value in each of these arrays is the rightmost index in the V specification. AVS/Express uses zero-based indexing; i.e., the index of the first value in a dimension is 0. Note that the value specified by the maximum dimension is not included in the values retrieved or set in the array. This is not the same as the ":" range operator in the V language which does include the maximum value. For example, to get the first value in a dimension, you would set the min to 0 and the max to 1.
An output argument for get routines, an input argument for set routines containing the specified subarray. The number of values returned or set is the product of the range (max - min) in each dimension.
The status code (see Section 1.7, Return status [page 1-22]).
In the V, array data is defined as follows:
A program can access a subarray of data, as follows:
OMobj_id grp1_id, data_id;
int h, w, ncomps;
unsigned char*subarray;
int ndim=3, size[3], min[3], max[3];
int status;
...
stat = OMget_name_int_val(grp1_id, OMstr_to_name("h"), &h);
stat += OMget_name_int_val(grp1_id, OMstr_to_name("w"), &w);
stat += OMget_name_int_val(grp1_id, OMstr_to_name("ncomps"),
&ncomps);
if (stat != 3) return(0);
size[0] = ncomps;
size[1] = w;
size[2] = h;
subarray = (unsigned char *) malloc (150 * 150 * ncomps);
min[0] = 0; /* Range for the ncomps dimension: 0-3. */
max[0] = ncomps;
min[1] = 0; /* Range for the w dimension: 0-150. */
max[1] = 150;
min[2] = 0; /* Range for the h dimension: 0-150. */
max[2] = 150;
data_id = OMfind_subobj(grp1_id, OMstr_to_name("data"),
OM_OBJ_RD);
status = OMget_sub_barray(data_id, 3, size, min, max,
subarray);
if (status == 0) {
return(0); /* value is not set */
}
OMget_uniq_name returns an object name that is unique among parent's immediate subobjects. You supply a suggested name. The returned name is either the suggested name or, if the name already exists in parent, the suggested name with #n appended.
The third argument must be NULL.
int OMinsert_obj_ref (
OMobj_id referencing_object,
int index,
OMobj_id referenced_object,
int mode );
int OMXobj::insert_obj_ref(
int index,
OMobj_id referenced_object,
int mode = 0 );
OMinsert_obj_ref inserts a connection referencing_object's list of connections to referenced_object at the location specified by index. This routine is similar to OMadd_obj_ref but provides control over the order of execution.
OMinsert_obj_ref is useful when operating on an object that has an array of connections where the order of the connection list is important.
For making special types of connections, call OMinsert_link_objs.
The index into the array of connections.
The mode argument can specify the value OM_OBJ_REF_QUERY to obtain a status code that indicates whether or not the connection will be valid without actually making the connection. For normal operation, specify 0 for the mode.
The status code (see Section 1.7, Return status [page 1-22]).
OMadd_subobj makes object an immediate subobject of parent.
Positionally, object becomes object number index in parent, where an index value of zero refers to the first object. If you don't care about object's placement in parent, use OMadd_subobj instead.
The id of the new parent object. parent must be an object that can have subobjects, such as SingleWindowApp, Applications, or a library, group, or macro object.
The location of the new object in parent. 0 means the first subobject; 1 means the second subobject, and so forth.
You can specify OM_ARRAY_APPEND to add the object to the end of the subobject list.
The id of the object being given a parent. object must not currently have a parent.
The fourth parameter must be 0.
The status code (see Section 1.7, Return status [page 1-22]).
OMis_null_obj is a C macro which tests whether an object id is NULL.
The returned value indicates whether the object id is NULL:
/* Test whether val1_id is null. */
OMobj_id val1_id;
...
if (OMis_null_obj(val1_id))
printf("Object id is NULL\n");
int OMlink_objs(
OMobj_id input_object,
OMobj_id output_object);
int OMinsert_link_objs(
OMobj_id input_object,
int index,
OMobj_id output_object)
These routines are alternatives to the routines OMadd_obj_ref and OMinsert_obj_ref for making a connection between two objects. OMlink_objs is the routine used by the Network Editor to make connections. It makes the connection symbolically by creating a name-link object to maintain the connection. The intermediate name-link object has slightly more overhead but is useful in two situations.
If you are making the connection to a subobject of a group with reference mode by-reference (i.e., &), the name-link object makes the destination of the connection the subobject of the reference's value and automatically relinks the connection as the group reference's value changes. For example, if you have the V code
group &ref {
int a;
} => val;
group val {
int a;
};and you use the OMlink_objs function with the output_object set to ref.a, the connection's value becomes val.a. As the ref object's value changes, so does the value of the connection.
If you are making a connection to a subobject of an array of group objects, the name-link object allows that connection to form an array of connections to the appropriate subobjects of the array of groups. For example, if you have the V code
and you use the OMlink_objs function with input_object set to input and output_object set to arr, this forms an array of connections so that effectively input[0] is set to arr[0].a, input[1] is set to arr[1].a, and so on.
OMinsert_link_objs is the same as OMlink_objs but allows you to insert connections rather than just appending them onto the end of the list. This is useful when the order of the connections is important.
The source end of the connection.
The destination end of the connection.
The index of the new value in the list of connections. The existing connections are moved ahead in the list.
The status code (see Section 1.7, Return status [page 1-22])
For UNIX systems:
int OMmain_init (
int argc,
char * argv );
For PC systems:
int OMmain_init(
HINSTANCE hInst,
HINSTANCE hPrevInst,
LPSTR CmdStr,
int CmdShow );
OMmain_init initializes the Object Manager. As part of the initialization, object libraries are loaded according to the templ.v file.
You call OMmain_init whenever you write your own C or C++ main function.
The arguments argc and argv specify command-line arguments. OMmain_init scans for and processes AVS/Express-specific arguments, such as -vcp. This routine notifies you about arguments that it does not understand. You should remove any arguments from argc and argv (or CmdStr for PC's) that are not recognized by AVS/Express before calling this routine.
As part of using OMmain_init, you must create two functions, PREinit and BASEinit. OMmain_init calls PREinit before loading libraries and BASEinit after loading libraries.
You typically either create routines that are empty, or use functions generated for you in processname.c for a particular process.
The routines have the following prototypes:
void PREinit (int * argc, char * argv);
void BASEinit (int * argc, char * argv);Notice that with PREinit and BASEinit the argc parameter is a pointer to an integer.
The number of arguments in argv.
A VCP mode that can be submitted to a subsequent call to OMmain_loop. For example, if argv contains the -vcp argument, then OMmain_init returns OM_VCP_PRESENT.
OMis_main_process determines whether the calling process is the scheduler.
1 if the process is the scheduler; 0 if not.
OMmain_loop starts the main loop for dispatching events, such as user interactions with your application.
You typically call OMmain_loop when executing in server mode. First you initialize the application, including calling OMmain_init to initialize the Object Manager. Then you call OMmain_loop. OMmain_loop never returns.
The routine also optionally starts up the V Command Processor.
A mode indicating whether to start the V Command Processor:
OMname_to_func queries AVS/Express' internal table that maps functions to function names, and returns the function corresponding to a specified name.
The function's name as it appears in a method object's value expression.
/* Return the function corresponding to id "add numbers". */
OMpfi function;
...
function = OMname_to_func("add numbers");
OMname_to_str returns the character string corresponding to an object name. Do not modify and do not free the string returned by this routine.
OMstr_to_name returns the object name corresponding to a character string.
The Object Manager does not store and manipulate an object's name directly, but rather allocates a unique integer value that maps directly to a particular character string. OMobj_name holds that integer value.
The routines described here convert between the two representations of the string.
An object's name, as a OMobj_name.
An object's name, as a character string.
OMobj_name object_name; // An integer.
char object_string[30];
...
object_name = OMstr_to_name("My string");
strcpy(object_string, OMname_to_str(object_name));
OMobj_is_type_of determines whether object's primitive type is type.
The include file <avs/om_type.h> defines the type variables you can specify for type, including the following common ones:
Alternatively, you can use the routine OMstr_to_type to return the type id corresponding to the type's string name.
1 if the object's primitive type is type; 0 if not; or -1 on an error.
OMobj_proc is a macro which returns the process id of an object.
OMopen_file loads either an ascii or binary V file specified from user_file into object_id
Specifies the object that is used as the parent of objects defined in user_file.
Specifies the name of an ascii or binary V file. If user_file does not have a suffix, this routine first tries to append a .v suffix onto the filename and open an ascii V file of this name. If that file does not exist, it appends a .vo suffix and tries to open a binary V file with that name.
If either the file was originally specified with a suffix or if neither .v or .vo files exist, this routine identifies the file as either binary V or ascii V by looking at the contents and loads the file.
The file specified can be an absolute pathname or relative to v subdirectory of any project in your XP_PATH or relative to the current directory in which your process was started.
The third argument specifies the mode in which to load the file. The only supported value is 0.
The status code (see Section C.7, "Return status" [page C-26])
OMparse_buffer reads and parses an input string consisting of V statements, V commands, and V comments. OMparse_buffer returns when it encounters a NULL termination character in the buffer.
The Object Manager interprets the statements and commands in the context of the object identified by object. Any new objects defined in the buffer are created as subobjects of the object argument.
Error messages are sent to stderr.
A pointer to a NULL-terminated string consisting of V commands.
The third parameter must be 0.
The status code (see Section 1.7, Return status [page 1-22]). a 0 return status indicates that syntax errors were encountered parsing the buffer.
Given the id of a group object defined in V as
you can add a subobject to this object with
The resulting definition of myobj is
int OMparse_obj_val (
OMobj_id object,
char *buffer);
int OMparse_obj_ref (
OMobj_id object,
char *buffer);
OMparse_obj_val reads and parses an input string consisting of a valid definition for the value of a V object. The buffer argument contains any characters that can be placed after the "=" operator in a V statement and before the ";" statement terminator. Calling this routine has the same effect as entering this string in the VCP.
OMparse_obj_ref is the same as OMparse_obj_val except that it uses the "=>" operator instead of "=".
Error messages are sent to stderr.
A pointer to a NULL-terminated string consisting of V commands.
The status code (see Section 1.7, Return status [page 1-22]). A 0 return value indicates that syntax errors were encountered in the statement definition.
OMparse_stream reads and parses an input stream consisting of V statements, V commands, and V comments. OMparse_stream returns on an EOF condition.
The Object Manager interprets the statements and commands in the context of the object identified by object.
Error messages are sent to stderr.
The status code (see Section 1.7, Return status [page 1-22]). A 0 return status indicates that syntax errors were encountered in the stream.
OMprint_obj prints the definition of the specified object to standard out.
Since you frequently want to call this routine from the debugger, you can use the alternate routine OMprint_obj_ptr when your debugger does not allow you to call functions that take structures as arguments. This routine takes the two members in the OMobj_id structure as separate arguments.
The elem_id field of the object_id. This routine is designed to be used when debuggers are unable to call functions with structures as arguments.
The proc_id field of the object_id.
OMprint_notifies prints the notifications on an object to standard out.
OMprint_path prints the full pathname of an object to standard out.
You can use the alternate for OMprint_path_ptr when calling this routine from a debugger that does not allow passing structures as arguments. It takes as its arguments the two members of the OMobj_id structure: elem_id, and proc_id.
The elem_id field of the object_id. This routine is designed to be used when debuggers are unable to call functions with structures as arguments.
The proc_id field of the object_id.
This routine causes the process specified to exit when it has finished the operation that it is currently executing. If it is called with the constant OMlocal_proc_id, it causes the current process to exit but waits until the main event loop is reached. In other words, this routine returns if it is asked to exit the local process but will cause this process to exit when the event handler that triggered this operation returns.
The process id of the process that should be asked to exit. The main process always has a process_id of 0. You can get the process id of any object using the OMobj_proc macro. The process id of the current process is stored in the global variable OMlocal_proc_id.
Specifies the exit status code for the process to exit.
unsigned int OMpush_ctx (
OMobj_id context_id,
int state_mode,
int notify_mode,
int child_notify_mode );
int OMpop_ctx (
OMobj_id context_id );
unsigned int OMXobj::push_ctx(
int state_mode = 0,
int notify_mode = 0,
int child_notify_mode = 0);
int OMXobj::pop_ctx(void);
These routines suspend and resume AVS/Express' execution in the context of a specified object.
OMpush_ctx suspends execution, meaning that, in general:
- Notifications that have the same function id or argument id as context_id are suppressed. They are never executed.
- All other notifications are queued.
OMpush_ctx also sets the state_mode with the state_mode argument. The state mode determines how object's values are saved during the save operation. If you only want to set the state mode without affecting how events are queued, use the routine OMset_state_mode.
OMpop_ctx can be made to execute the notifications queued by the most recent OMpush_ctx command. It also restores the state mode to its previous value.
You can modify the treatment of notifications with the event_mode and child_notify_mode arguments.
Calls to OMpush_ctx and OMpop_ctx can be nested. A nested push/pop context is known as the child context of the enclosing push/pop context. The enclosing context is known as the parent context.
Calls to OMpush_ctx and OMpop_ctx bracket the invocation of any method's callback routine. Since calls to OMpush_ctx can be nested, you can still call these routines to control events generated from within the module's compute function.
Even if the OMpop_ctx executes the update functions of all outstanding methods, in some cases a widget's display will not have been updated after the OMpop_ctx call. This is because the widget sends itself a window system expose event which is not delivered with OMpop_ctx. To guarantee that all widgets are also updated, you should call the routine EVflush_events after calling OMpop_ctx.
In OMpop_ctx, context_id must be the same id as the one specified in the most recent call to OMpush_ctx.
The context_id is used as a filter to prevent a method from sending notification events to itself. Any events that are delivered to the object specified by context_id are not delivered unless the notify_mode argument is specified as OM_CTX_ALL_NOTIFIES.
An integer indicating whether changes to the application's network should be saved when the user performs a save operation. Specify one of the symbolic constants (defined in <avs/om.h>):
An integer indicating how AVS/Express should treat notifications that occur during the push/pop context.
AVS/Express always suppresses notifications that have the same function id or argument id as context_id.
All other notifications are either queued until the pop, or queued until the parent's pop, or suppressed. Specify one of the following symbolic constants (defined in <avs/om.h>):
An integer specifying the notify mode of all child contexts. Specify one of the following symbolic constants listed under the notify_mode argument.
When push/pop contexts are nested, a child's notification mode is the OR'd combination of:
- The notify_mode argument specified by the child.
- The child_notify_mode arguments specified by any outer-level push/pop context. Put another way, the child notify mode specified by a push/pop context is in effect for all inner contexts, including children, their children, and so forth.
Here is a simple push/pop context that executes all events setting the state mode so that all changes made in the context will be saved:
OMpush_ctx(obj_id, OM_STATE_PROG, 0,0);
// any notifications that are triggered here....
OMpop_ctx(obj_id); // are executed during this call
Here is a simple push/pop context that sets the state mode so that no changes made in the context will be saved and delays executing notifications until the parent context is popped:
OMpush_ctx(obj_id, OM_STATE_TRANSIENT,
OM_CTX_PARENT_NOTIFIES, 0);
// any notifications that are triggered here...
OMpop_ctx(obj_id); // are not executed here (unless there is
// no parent context)
These routines allow you to encapsulate a subroutine that uses the OMstatus_check routine to set the percent_done value. The subroutine sets percent done from 0 to 100. These routines determine how much contribution the subroutine has on the percent done of the calling routine.
After calling OMpush_status_range, a percent_done argument of 0 in OMstatus_check is mapped to this value.
After calling OMpush_status_range, a percent_done argument of 100 in OMstatus_check is mapped to this value.
You might have a function that computes an array of numbers called get_random_values. This function is coded so that it calls OMstatus_check at intervals from 0 to 100 as it walks through elements in the array. You then write a module which calls this function multiple times with different sized arrays. The higher level function can set a status range before calling the lower level function:
int
get_random_values(int arr[], int size)
{
int i, stop;
for (i = 0; i < size; i++) {
if (!(i & 0xf)) { /* do only every so often... */
(void) OMstatus_check(i * 100 / size, NULL, &stop);
if (stop) return(0); /* user interrupted us */
}
arr[i] = random();
}
return(1);
}
int
update_me(OMobj_id obj_id, OMevent_mask mask, int seq_num)
{
int arr1[1000], arr2[500];
int stat;
OMpush_status_range(0,75);
stat = get_random_values(arr1,1000);
OMpop_status_range();
if (stat != 1) return(0); /* interrupted */
OMpush_status_range(75,100);
stat = get_random_values(arr2,500);
OMpop_status_range();
if (stat != 1) return(0);
... set the values in arr1 and arr2 into objects...
OMread_desc reads an ascii V file into AVS/Express. New objects defined in the V file become subobjects of parent.
The id of an object. parent can be any object that can have subobjects, such as SingleWindowApp, Applications, or a library, group, or macro.
You cannot specify OMnull_obj for parent.
The name of a V file. You can specify an absolute pathname or a path relative to the current directory of the calling process.
The status code (see Section 1.7, Return status [page 1-22]). A 0 return status indicates that errors were encountered while parsing the file.
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);
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:
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).
The mode in which to retrieve the value for the array:
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.
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.
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.
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);
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
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).
The mode in which to retrieve the value for the array:
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.
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.
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.
OMret_obj_name returns an object's name as a character string.
A character string containing the object's name. You are not allowed to modify the returned value under any circumstances, and you must not free it .
On failure, OMret_obj_name returns the string "<invalid>" or "<null"> if given OMnull_obj as an argument.
OMret_obj_parent returns the parent object for the object specified.
The id of the object whose parent is returned.
The id of the parent object. If the object_id parameter is invalid or of the object has no currently defined parent, OMnull_obj is returned.
OMret_obj_path returns the full pathname of an object.
The address of a character buffer in which to store the pathname. If you pass a NULL buffer, OMret_obj_path ignores the buffer_size argument and returns a malloced string. You should free the string when you're done with it by using free().
The size of the buffer, in bytes. OMret_obj_path returns at maximum this many bytes.
On success, the address of object_name_buffer.
On failure, OMret_obj_path returns the string "<invalid>" or "<null>.".
/* Print val1_id's full pathname. */
OMobj_id val1_id;
char val1_name[100];
int bufsize = 100;
...
printf("%s\n", OMret_obj_path (val1_id, val1_name, bufsize));
char *OMret_obj_path_to (
OMobj_id object_id,
OMobj_id upto_object_id,
char *object_name_buffer,
int buffer_size );
OMret_obj_path_to returns the pathname of an object, qualified up to a specified object.
The id of the object up to which the pathname of object_id should be qualified. If upto_object_id is not in object_id's path, the routine returns object_id's full pathname.
The address of a character buffer in which to store the pathname. If you pass a NULL buffer, OMret_obj_path_to ignores the buffer_size argument and returns a malloced string. You should free the string when you're done with it by using free().
The size of the buffer, in bytes. OMret_obj_path_to returns at maximum this many bytes. Names are truncated from the start of the pathname and ellipses are inserted when this limit is reached.
A character string containing the object's unqualified name.
On failure, OMret_obj_path_to returns the string "<invalid>" or "<null>."
/* Print val1_id's pathname up to my_app_id. */
OMobj_id val1_id, my_app_id
char val1_name[100];
int bufsize = 100;
...
printf("%s\n", OMret_obj_path_to (val1_id, my_app_id,
val1_name, bufsize));
OMret_omx_ptr returns a pointer to the C++ object associated with the AVS/Express object object_id. You use this routine when you have an existing AVS/Express object that you want to manipulate with the C++ API.
This C++ object returned is a pointer to an OMXgroup.
In order for this routine to be used, the system must have a compiled definition of a C++ class corresponding to the object and the object must be in the same process as the code calling this routine.
C++ classes are generated for objects that have the export_cxx property set or for modules that have a cxxmethod.
The object whose C++ class is returned.
The second argument must be 0.
This routine returns a pointer to a C++ object of type OMXgroup. The OMXgroup class supports a method called OMXgroup::ret_omx_ptr that you must use to convert this pointer to a pointer of a more specific class.
If there is not an existing C++ object associated with the object specified, but AVS/Express does have a class associated with this object (or a template object that this object was created from), a new C++ object is created and a pointer to this newly created object is returned. If there is no defined class associated with this object, an error message is printed and a NULL pointer is returned.
You should not delete the object returned to you by this routine. It is deleted by AVS/Express when the object is destroyed.
OMret_str_array_val returns a string from an object that defines an array of strings. It is an easier alternative to using the OMget_str_array_val routine but provides access to the same value. AVS/Express currently only supports one-dimensional arrays of strings.
This routine is used in one of two modes:
- The string value is allocated with malloc and must be freed by the user
- The memory to store the string is supplied by the caller. If the string is too large to fit, it is truncated.
The object id of an object that has a string value.
The index into the array of the desired string. This value should be between 0 and one less than the value provided by the routine OMget_array_size.
If the value is NULL (or if the buffer_size parameter is 0) space is allocated for the string. If this parameter is not NULL (and the buffer_size argument is greater than 0), this argument specifies a pointer to memory in which to store the string. This pointer is returned by the function in this case.
Specifies the size of the buffer argument. If this argument is 0, the buffer argument is ignored.
A pointer to a NULL terminated string containing the specified string in the array of strings is returned. This value should be freed using the C routine free if the buffer argument is NULL or if buffer_size is 0.
char *OMret_str_val(
OMobj_id object_id,
char *buffer,
int buffer_size );
char *OMret_name_str_val(
OMobj_id parent_id,
OMobj_name subobject_name,
char *buffer,
int buffer_size );
This routine returns the string value for the object specified. It is an easier alternative to using the OMget_str_val routine but provides the same value.
It is used in one of two modes:
- The string value is allocated with malloc and must be freed by the user
- The memory to store the string is supplied by the caller. If the string is too large to fit, it is truncated.
This specifies the object id of an object that has a string value.
If the value is NULL (or if the buffer_size parameter is 0) space is allocated for the string. If this argument is not NULL (and the buffer_size argument is greater than 0), this parameter specifies a pointer to memory in which to store the string. This pointer is returned by the function in this case.
Specifies the size of the buffer argument. If this argument is 0, the buffer argument is ignored.
A pointer to a NULL terminated string containing the string value of the object specified. This value should be freed using the C routine free if the buffer argument is NULL or if buffer_size is 0.
Most OMset_xxxx routines are described with the OMget_xxxx routines.
OMobj_id object_id,
int type,
char *array_pointer,
int size,
int mode );
int OMXobj::set_array (
int type,
char *array_pointer,
int size,
int mode = OM_SET_ARRAY_COPY )
OMset_array sets the value of an array object; i.e., all elements in the array.
This routine cannot be used for objects of type string or ptr.
You use OMset_array when the calling process has already created an array and needs to set the array object to that array. If the dimensions of the array are defined before you need to access the array, you may find it easier to use the routines: OMret_array_ptr, OMret_typed_array_ptr or OMget_array. These routines can be used to get a pointer to the array which you can then read, write or read and write. The OMset_array routine can only be used for write-only operations.
The integer code for the array's data type. type must be compatible with the object's type. For example, if the object is integer, then the array could be any numeric type; AVS/Express performs any necessary conversion.
AVS/Express provides the following symbolic constants, defined in <avs/om.h>:
The address of the array being written.
The total number of values in the array.
The array's length should equal the size of the array object. In the following example, object myarray's size is 300, the product of each dimension, so the array that is written should contain 300 values and length should equal 300:
The target object can have at most one dimension that does not specify a size. For example, if myarray is defined as follows:
then the array can be any size.
If the target object is multidimensional and one of the dimensions does not specify a size, then the array's total size must be a multiple of the sizes specified. For example, if myarray is defined as follows:
then the array's size must be a multiple of 6.
How AVS/Express should set the array. Specify one of the following symbolic constants:
The status code (see Section 1.7, Return status [page 1-22]).
int OMset_obj_iarray_prop(
OMobj_id object_id,
OMobj_name property_name,
int nvalues,
int values[]);
This routines sets the value of a property on an object which is defined by an integer array of values. It is most useful to set the value of the NEportLevels property when you are setting the number of input port levels to be different than the number of output port levels. If you are setting both to the same value, you can use OMset_obj_iprop instead.
The object whose property you want to set.
The property name of the property you want to set. This can either be one of the global variables defined in <avs/om_att.h> or <avs/ne_om.h> or the return value from the function OMstr_to_name.
The number of values in the array.
The values in the array. These values are copied out of the location specified by the values argument.
The status code (see Section 1.7, Return status [page 1-22]
Here is an example that sets the NEportLevels property on the object in the variable obj:
int values[2];
values[0] = 2;
values[1] = 3;
OMset_obj_iarray_prop(obj, OMstr_to_name("NEportLevels"),
2, values);
int OMset_obj_ref (
OMobj_id referencing_object,
OMobj_id referenced_object,
int mode );
int OMXobj::set_obj_ref (
OMobj_id referenced_object,
int mode = 0);
OMset_obj_ref makes a connection in referencing_object to referenced_object.
OMset_obj_ref is useful for making a single connection. If the referencing object is already connected to an object, that connection is replaced by the new connection.
If the referencing object is a scalar, the referenced object must also be a scalar. If the referencing object is an array, the referenced object must also be an array.
To connect an object to an array of objects, call OMadd_obj_ref instead.
The id of the referencing object.
The id of the referenced object.
You can specify OMnull_obj. The Object Manager simply breaks the current connection so that referencing_object is no longer connected to anything.
The mode argument is typically specified as 0. If you specify a mode argument of OM_OBJ_REF_RDONLY, you create a read-only connection. For primitive values, a read-only connection is broken whenever a set operation applied to the referencing object.
The status code (see Section 1.7, Return status [page 1-22]).
OMset_state_mode is a C macro that sets the state mode to the mode supplied. The state mode is a part of the current context that determines how changes made are saved using the save operation. It is also set through OMpush_ctx and is restored when an OMpop_ctx call is made. As long as you make the OMset_state_mode call in between OMpush_ctx and OMpop_ctx calls, you do not need to restore the state mode after changing it. All methods are executed inside of OMpush_ctx and OMpop_ctx calls.
This argument specifies the state mode. It can be set to one of the values OM_STATE_PROG, OM_STATE_USR or OM_STATE_TRANSIENT. See OMpush_ctx and OMpop_ctx for details.
OMset_verbose sets the verbose mode for the events specified by mask.
One or more events whose verbose mode is to be set. Modes that are omitted are unaffected.
You can specify any of the following symbolic constants, which are defined in <avs/om.h>:
Whether to turn the specified modes on or off:
A file pointer indicating where the output should be directed. The default if fp is NULL is standard out.
/* Turn on verbose mode for OM_VERBOSE_FUNC and
OM_VERBOSE_EVENT. The output is sent to std out. */
OMset_verbose(OM_VERBOSE_FUNC | OM_VERBOSE_EVENT, 1, NULL);
OMstatus_check performs two functions:
- updates the current status information (percent done and module name)
- optionally returns an interrupt flag that indicates if this object has been interrupted
This function should only be called from within the callback function of a method. In order for this function to work, you should have enabled status display for your method by setting the status property to 1. In V, you can do this with:
There is some overhead for calling this routine. You should try to avoid calling it more than is necessary, roughly a few times per second of execution.
If your module is not contained in a single function, you may sometimes want to bracket lower level operations that are used by several different higher level operations and thus cannot accurately predict what range of execution time they will occupy. You can use the routines OMpush_status_range and OMpop_status_range to perform this function.
This integer sets the percent done flag in the scheduler. This is a number between 0 and 100 that indicates roughly what percentage of the current method's work has been completed so far. This value is displayed to the user through a status bar. Setting this to a 0 value prevents flag from being updated.
This string specifies the module name or other information that is displayed with the status information. You can use it to display a short one-line message about what operation is currently proceeding. If this value is passed as NULL, this field is not updated.
When this value is returned as 1, it indicates that the user has attempted to interrupt the current operation. Your method should then take whatever steps are necessary to abort the current operation and return as soon as possible. If you are not going to honor this flag, you should pass a NULL value for this parameter as there is some overhead for calling this routine.
This example shows how you might place the OMstatus_check call into a loop inside of a module's update method:
for (i = 0; i < size; i++) {
if (!(i & 0xff)) { /* do only every so often... */
(void) OMstatus_check(i * 100 / size, NULL, &stop);
if (stop) return(0); /* user interrupted us */
}
// insert the body of the loop here
}
A status code. See Section 1.7, Return status [page 1-22].
OMstr_to_type returns the type id corresponding to type_name.
The name of a primitive type, such as group, macro, or int, specified as a string.
The type id corresponding to type_name; NULL on an error.
OMupd_name_refsshould be used after you have moved an object in the object hierarchy (with OMdel_subobj, OMinsert_subobj) or changed an object's name. You need only call this routine if the may have connections to it that need to be updated by this change.
This routine updates the values of any name-link objects that are connected to this object so that they will use the new pathname in the future.
The object whose name has been changed or has been moved in the object hierarchy.