NAME

cxLatPtrSet - set lattice data and coordinate pointers

C SPECIFICATION

#include <cx/DataAccess.h>

cxErrorCode cxLatPtrSet(cxLattice *src, cxData *data, void *dataVal,
  cxCoord *coord, void *coordVal)

FORTRAN SPECIFICATION

integer function cxLatPtrSet(src, dataHand, pDataVal, coordHand, pCoordVal)
integer src
integer dataHand, pDataVal
integer coordHand, pCoordVal

pointer (pDataVal, dataVal), (pCoordVal,coordVal)
integer dataVal(*), coordVal(*)

PARAMETERS

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.

FUNCTION RETURN VALUE

Returns an integer error code enumeration.

DESCRIPTION

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.