NAME

cxInputDataGet, cxInputDataGetV - retrieve the data on a particular input port

C SPECIFICATION

#include <cx/PortAccess.h>

void *cxInputDataGet(int port)

int cxInputDataGetV(int port, void **dataVec[] )

FORTRAN SPECIFICATION

integer function cxInputDataGet(port)
integer port

integer function cxInputDataGetV(port, pDataVec)
integer port
pointer (pDataVec, dataVec)
integer dataVec(1)

PARAMETERS

port: The integer descriptor of the port from which the module wants data.
dataVec: Address of array of pointers to data objects fanned into port.

FUNCTION RETURN VALUE

cxInputDataGetV returns the number of values in the array.

DESCRIPTION

cxInputDataGet returns a handle to the data object present on the given port. If there is no data on the port, it returns a NULL (C) or zero (Fortran) value. In the C usage, the (void *) pointer must be recast to one of the standard IRIS Explorer data types, such as cxLattice. In the Fortran usage, the integer handle must be passed to an interface routine compatible with the IRIS Explorer data type of the input port, such as cxLatDescGet for cxLattice data.

Since release 2.0, IRIS Explorer has allowed simultaneous access to all of the data values fanned into a single port. For example, more than one output of type cxGeometry are usually connected to the Render module, so that it may display all the geometry together. cxInputDataGetV sets dataVec to the address of an array of pointers to data, one for each connection on the port, and returns the length of the array. The dataVec array is static, and must not be deallocated. Note that the length of this array is not always the same as the number of connections on the port: if the last connection on a port is disconnected, the last data present remains, and cxInputDataGetV will return an array of length one, and its connection identifier will remain unchanged. There are two ramifications of deleting the last connection: cxInputDataGetV will return data for the last connection and a length of one, while cxInputConnectsGet will return 0.

Calling either routine will cause the state of the port to be old the next time the module fires, unless new data actually arrives. If cxInputDataGet or cxInputDataGetV is not called, the port state will still be new the next time the module fires, although the previous data may get replaced by newer data.

These routines should not be called for a "Fire" port. Data on this port is made old automatically when the module's computational function returns to the control wrapper.

Note that required ports only require some data to be present before the module can fire, so cxInputDataGet will never return NULL for a required port. The array returned by cxInputDataGetV may have NULL values in it, but at least one value will not be NULL. This allows modules that support fan-in to accept empty connections. For example, the Render module can display a scene even if one of its inputs has never fired. Modules that intend to support fan-in through the use of cxInputDataGetV must check for NULL values in the dataVec array.

Most modules don't need to support fan-in. If data is fanned into a port, then cxInputDataGet returns data from the newest connection which has new data. If no connection has new data, then data is returned from the newest connection. This is the connection operated on by cxInputDataConnIDGet, cxInputDataChanged, and cxInputDataRelease.