NAME

cxLatPtrSet - set lattice data and coordinate pointers
#include <cx/DataAccess.h>

cxErrorCode cxLatPtrSet(cxLattice *src, cxData *data, void *dataVal, cxCoord *coord, void *coordVal)
integer function cxLatPtrSet(src, dataHand, pDataVal, coordHand, pCoordVal)
integer src
integer dataHand, pDataVal
integer coordHand, pCoordVal

pointer (pDataVal, dataVal), (pCoordVal,coordVal) integer dataVal(*), coordVal(*)
src
Lattice to be changed.
data
New cxData structure to be inserted into lattice.
dataVal
Pointer to new data values to be inserted into lattice data section.
coord
New cxCoord structure to be inserted into lattice.
coordVal
Pointer to new coordinate values to be inserted into lattice coordinate section.
Returns an integer error code enumeration. cxLatPtrSet sets pointers to the data or coordinate structures in a lattice, or to the data or coordinate information. If any pointer is NULL, then the assignment is not attempted.

Although it is possible to directly set the cxData pointer in a lattice, cxLatPtrSet is the interface for doing so. All IRIS Explorer data types contain reference counts, and are reclaimed when the reference count goes to zero. To replace the data section of a lattice using cxLatPtrSet is:

cxData *newData;
cxLattice *lattice;
...
cxLatPtrSet( lattice, newData, NULL, NULL, NULL );
If cxLatPtrSet is not used, the programmer must correctly increment and decrement reference counts:
cxData *newData;
cxLattice *lattice;
...
cxDataRefDec( lattice->data );
lattice->data = newData;
cxDataRefInc( lattice->data );
The old cxData in the lattice will be deleted by cxDataRefDec if no other process refers to it. Using cxLatPtrSet is less error prone to code, and allows module code maintain compatibility with future releases. cxLatPtrSet returns cx_err_none on success.

The Fortran user can set the dataVal and coordVal arrays by using the Fortran Pointer construction to equivalence the integer memory address and the start of the desired array, as indicated in the Fortran specification above.

The user can tell the function not to get information on a particular field by passing a NULL pointer value. You need not create dummy variables in the calling routine which calls cxLatPtrSet, because the request is simply ignored when the pointer comes in NULL.

cxLatNew(3E), cxLatRootNew(3E), cxLatCoordNew(3E), cxLatDataNew(3E)
Last modified: Mon Nov 6 16:33:27 GMT 2000
[ Documentation Home ]
© The Numerical Algorithms Group Ltd, Oxford UK. 1999