The cell library needs to have certain information about any cell file on which it acts; for example, it needs to know the handles of the VM file and of the row blocks. That information is kept in a
CellFunctionParameters
structure. The geode which uses a cell file is responsible for creating a
CellFunctionParameters
structure. The C definition of the structure is shown below.
Code Display 19-1 CellFunctionParameters
typedef struct { CellFunctionParameterFlags CFP_flags; /* Initialize this to zero. */ VMFileHandle CFP_file; /* The handle of the VM file containing * the cell file. Reinitialize this each * time you open the file. */ VMBlockHandle CFP_rowBlocks[N_ROW_BLOCKS]; /* Initialize these to zero. */ } CellFunctionParameters;
In order to create a cell file, you must create a
CellFunctionParameters
structure. Simply allocate the space for the structure and initialize the data fields. When you call a cell library routine, lock the structure on the global heap and pass its address. Geodes will usually allocate a VM block in the same file as the cell file, and use this block to hold the
CellFunctionParameters
structure; this ensures that the structure will be saved along with the cell file. They may often declare this to be the map block, making it easy to locate (see the VM chapter). However, this is entirely at the programmer's discretion. All that the cell library requires is that the structure be locked or fixed in memory every time a cell library routine is called.
The
CellFunctionParameters
structure contains the following fields:
CFP_flags
CellFunctionParameters
structure, thus indicating that the structure ought to be resaved. After you save it, you may clear this bit.
CFP_file
CFP_rowBlocks
One warning: The cell library expects the
CellFunctionParameters
structure to remain motionless for the duration of a call. Therefore, if you allocate it as a DB item in the same VM file as the cell file, you must
not
have the structure be an ungrouped item. Remember, all the cells are ungrouped DB items; allocating or resizing a cell can potentially move any or all of the ungrouped DB items in that file.