op_esys_interface_array_get()
Abstract
Places the contents of a vector interface into an array.
Syntax
op_esys_interface_array_get (interface, value_ptr, start_offset)
| Argument | Type | Description |
|---|---|---|
interface |
Esys_Interface |
esys interface ID from which to read data [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(), as well as from op_intrpt_esys_interface().] |
value_ptr |
void* |
pointer to the array that is to receive data [The array must already be allocated.] |
start_offset |
int |
position in array that will receive the first element from the vector interface |
Return Type
int
Completion code indicating whether the operation completed successfully.
OPC_ESYS_SUCCESS means the operation was successful. For the remaining completion codes, see Table 53 “External System Completion Code Symbolic Constants“ on page 13.
Example
/* Get values from both high and low-order data buses; concatenate into one array. */
op_ima_obj_attr_get (bus_a, "dimension", &bus_a_width);
op_ima_obj_attr_get (bus_b, "dimension", &bus_b_width);
val_array = (char *) op_prg_mem_alloc (sizeof (char) * (bus_a_width + bus_b_width));
/* First bits are placed in val_array, starting at position 0. */
op_esys_interface_array_get (bus_a, val_array, 0);
/* Remaining bits are placed starting at the bus_a_width position in val_array. */
op_esys_interface_array_get (bus_b, val_array, bus_a_width);
Details
The array that receives the contents of the vector interface must already be allocated. The array receives values starting in its initial position (index 0) when the start_offset argument is zero. Be certain that the array is large enough to hold all values in the vector interface, because the procedure writes to successive memory locations until all elements of the vector interface have been placed into the array.
It is also possible to write to the array at positions other than the initial one by setting the start offset argument to the index number of the array that is to receive the first value from the vector interface.
Purpose
Provide a way to write the contents of a vector interface to a specified location in memory.
Errors
- Program Abort: Segmentation violation. (due to improperly allocated array pointer argument
- Program Abort: Segmentation violation. (due to incompatible esys interface data type and array pointer
- Recoverable Error: Interface handle is invalid.
- Recoverable Error: Attempt to get a value from an esys output interface (
<name>). - Recoverable Error: Attempt to get a vector or array value from a non-vector interface (
<name>).
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_set() to place elements from an array onto a vector interface
- Use the KP op_esys_interface_value_get() to place the value of an esys interface into a variable
- Use the KP op_esys_interface_vector_get() to place elements from a vector interface into a value vector