op_esys_interface_array_set()
Abstract
Sets values of a vector interface using an array.
Syntax
op_esys_interface_array_set (interface, schedule_time, array, start_offset)
| Argument | Type | Description |
|---|---|---|
interface |
Esys_Interface |
esys interface ID for the vector interface to which the data will be written [You can get the esys interface ID from several KPs in the Topo and Id packages, such as op_topo_child() and op_id_from_name().] |
schedule_time |
double |
scheduled time to write the data to the vector interface (see Details for available constants) |
array |
void* |
pointer to the source array This array must have at least as many elements as the vector interface. It may have more elements, thereby allowing a portion of the array to be used to set the vector interface.] |
start_offset |
int |
index of the first element in the array to be written to the vector interface [The first element of the array does not necessarily have to be the first value set on the vector interface. This argument specifies which element of the array is to be written to the vector interface’s position 0. Subsequent elements of the array are read into subsequent positions on the vector interface until the vector interface is full.] |
Return Type
Evhandle
Handle to the OPC_INTRPT_ESYS_INTERFACE_EXT interrupt scheduled to set the interface, if one was scheduled; OPC_NIL otherwise.
Example
/* Read data to be applied to the vector interface from a file. */
data_array = (int *) op_prg_mem_alloc (interface_width * (sizeof (int)));
for (i = 0; i < interface_width; i++)
{
fscanf (file_ptr, "%d", data_array + i);
}
/* After the array has been read in, send the data to the vector interface */
/* at the current simulation time. */
op_esys_interface_array_set (interface_id, op_sim_time (), data_array, 0);
/* Deallocate the array. */
op_prg_mem_free (data_array);
Details
The value of start_offset refers to the array index, not the vector interface. Therefore, by setting the start_offset to 5, the first element of the vector interface (index 0) will be set to the value of the sixth position in the array (index 5). Thereafter, the second element of the vector interface will be set to the value in the seventh position in the array, and so on until all values of the vector interface have been set.
The array must be long enough to fill all elements of the vector interface because op_esys_interface_array_set() does not stop reading values from memory until all elements of the vector interface have been set.
The schedule_time argument can be an explicit time or one of the following special values:
- OPC_ESYS_NOTIFY_IMMEDIATELY—the interface value is delivered to the registered callback (if any) right away
- OPC_ESYS_NOTIFY_NEVER—the interface value is updated, but any registered callback is not invoked
Purpose
Provides a mechanism for setting the values of a vector interface using by using an array.
Errors
- Program Abort: Segmentation violation. (due to improperly-allocated array pointer argument)
- Program Abort: Segmentation violation. (due to incompatible esys interface data type and value)
- Recoverable Error: Interface handle is invalid.
- Recoverable Error: Attempt to set a value on an esys input interface (
<id>). - Recoverable Error: Attempt to set vector or array value on a non-vector interface (
<id>). - Recoverable Error: Attempt to set a value on an unconnected esys interface (
<id>). - Recoverable Error: Insufficient memory to set value on esys interface (
<id>). - Recoverable Error: Specified time (
<schedule_time>) is less than current time.
Reference
- Use the KP op_intrpt_esys_interface() to get the esys interface ID for an esys interface
- Use the KP op_esys_interface_array_get() to place elements from a vector interface into an existing array
- Use the KP op_esys_interface_value_set() to place the value of a single variable onto an esys interface
- Use the KP op_esys_interface_vector_set() to place elements from an value vector onto a vector interface