Synopsis
OMobj_id template,
OMobj_name newobj_name,
OMobj_id parent,
OMproc_id proc,
int mode );
Description
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.
Arguments
template
The id of a template object.
newobj_name
The name of the new object.
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.
parent
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.
proc
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.
mode
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.
Specify one of the following:
• 0 -- The instanced flag should not be set immediately. As a result, the Object Manager does not execute any methods defined in the object. To set the flag explicitly, call OMclose_obj.
• OMchanged .
• OM_COPY_CLOSE -- The instanced flag should be set. As a result, the Object Managerl executes the object.
Returned value
The id of the new object; or OMnull_obj on an error.
See also