NAME

cxInputDataConnIDGet, cxInputDataConnIDGetV - get a unique connection identifier for data

C SPECIFICATION

#include <cx/PortAccess.h>

long cxInputDataConnIDGet( int port )

int cxInputDataConnIDGet( int port, int *connIDs[] )

FORTRAN SPECIFICATION

integer function cxInputDataConnIDGet( port )
integer port

integer function cxInputDataConnIDGetV(port, count, connIDs)
integer port
integer count
integer connIDs(1)

PARAMETERS

port: The integer descriptor for a port.
connIDs: Set to the address of an array of integers that uniquely identify each connection.

FUNCTION RETURN VALUE

cxInputDataConnIDGet returns the connection identifier for the data on port.

cxInputDataConnIDGetV returns the number of values in the array.

DESCRIPTION

Connections between modules are given unique integer identifiers, starting at zero and increasing monotonically, for a single invocation of IRIS Explorer. cxParameter ports are connected to widgets by special pseudo-connections, which have the identifier -1. Parameter functions also appear as pseudo-connections whose identifiers start at -2 and count down. cxInputDataConnIDGet and cxInputDataConnIDGetV return the connection identifiers associated with the data returned by cxInputDataGet and cxInputDataGetV.

cxInputDataConnIDGet returns the identifier of the connection which provided the data returned by cxInputDataGet. This is the newest connection with new data, or if no data is new, the newest connection.

cxInputDataConnIDGetV sets connIDs to the address of an array of integers containing the connection identifiers of the connections into the given port. The number of identifiers in the array is returned. The connIDs array is static and must not be deallocated. The connection identifiers correspond to the data values in the array returned by cxInputDataGetV. The connection identifiers are in increasing order (the order of connection) with the following exception: The widget pseudo-connection is always in the first position of the array. If a parameter function is defined, it is next, otherwise the actual connections are next.

A parameter function is like an "in-line" module, which replaces fanned-in parameters with a new value. When a parameter function is defined, it replaces the actual connections on the port. The disconnect hook function is called for each connection present, and a connect hook function is called for the new parameter function. If a parameter function is removed, then the disconnect hook function is called for the parameter function, and connect hook functions are called for each of the connections. If a module is tracking connects and disconnects with the hook functions, the same connection will appear to be connected twice. Parameter functions are removed if any input connection on which they depend is disconnected.

These routines are useful for advanced modules that internally cache the data on their input ports, and need to know which cached data item to replace when new data arrives. In conjunction with the connect and disconnect hook functions, a module may retain the newest data object for all the connections on a port. Note, however, that when new data arrives on a connection, the old data on that connection is released. This implies that if a module needs to retain old data from a connection, it must explicitly increment the reference count on that data object with cxDataRefInc.

For example, the DisplayImg module retains all of the lattice inputs it has received on its input port, and when new data arrives, the new data replaces the old data previously received on that connection. Likewise, when a connection to DisplayImg's input port is removed, this module's disconnect hook function is automatically called by the control wrapper. The hook function then decrements the reference count on the geometry data from the newly removed connection and returns.

NOTES

The (set-param) scripting command allows a scalar value to be assigned to any parameter input port. In order to support this, all parameter ports will get a widget pseudo-connection (-1), whether or not a widget actually exists for that port.