Cell Library: 2.2 Using the Cell Library: Basic Cell Array Routines

GEOS SDK TechDocs

2.1 The CellFunctionParameters Structure

2.3 Actions on a Range of Cells

CellReplace(), CellLock(), CellLockGetRef(), CellDirty(), CellGetDBItem(), CellGetExtent()

The basic cell routines are simple to use. One argument taken by all of them is the address of the CellFunctionParameters structure. As noted, this structure must be locked or fixed in memory for the duration of a function call. You can also access cells in any of the ways you would access a DB item; for example, you can resize a cell with DBReAlloc() .

All of the routines use the VM file handle specified in the CellFunctionParameters structure.

To create, replace, or free a cell, call the routine CellReplace() . This routine takes five arguments:

• The address of the CellFunctionParameters structure.
• The element's row.
• The element's column.
• The address of the data to copy into the new cell. This must not move during the allocation; therefore, it must not be in an ungrouped DB item in the same VM file as the cell file. In particular, it must not be another cell. The data will not be changed.
• The size of the new cell. If you pass a size of zero, the cell will be deleted if it already exists; otherwise, nothing will happen.

If the cell file already contains a cell with the specified coordinates, CellReplace() will free it. CellReplace() will then allocate a new cell and copy the specified data into it. The routine invalidates any existing pointers to ungrouped DB items in the file.

Once you have created a cell, you can lock it with CellLock() . This routine takes three arguments: the address of the CellFunctionParameters structure, the cell's row, and the cell's column. It locks the cell and returns its address (the assembly version returns the cell's segment address and chunk handle). Remember, the cell is an ungrouped DB item, so its address may change the next time another ungrouped DB item is allocated or resized, even if the cell is locked.

Like all DB items, cells can (under certain circumstances) be moved even while locked. For this reason, a special locking routine is provided, namely CellLockGetRef() . This routine is just like CellLock() except that it takes one additional argument, namely the address of an optr. CellLockGetRef writes the locked item's global memory handle and chunk handle into the optr. You can translate an optr to a cell into a pointer by calling CellDeref() ; this is another synonym for LMemDeref() , and is identical to it in all respects.

If you change a cell, you must mark it dirty to insure that it will be updated on the disk. To do this, call the routine CellDirty() . This routine takes two arguments, namely the address of the CellFunctionParameters structure and the address of the (locked) cell. The routine marks the cell's item block as dirty.

Sometimes you may need to get the DB handles for a cell. For example, you may want to use a DB utility to resize the cell; to do this, you need to know its handles. For these situations, call the routine CellGetDBItem() . The routine takes three arguments: the address of the CellFunctionParameters structure, the cell's row, and the cell's column. It returns the cell's DBGroupAndItem value. You can pass this value to any of the DB...Ungrouped() routines, or you can break this value into its component handles by calling DBGroupFromGroupAndItem() or DBItemFromGroupAndItem() .

If you want to find out the bounds of an existing cell file, call the routine CellGetExtent() . This routine takes two arguments: the address of the CellFunctionParameters , and the address of a RangeEnumParams structure. For the purposes of this routine, only one of its fields matters, namely the field REP_bounds . This field is itself a structure of type Rectangle , whose structure is shown below in Rectangle. CellGetExtent() writes the bounds of the utilized section of the cell file in the REP_bounds field. The index of the first row which contains a cell will be written in the rectangle's R_top field; the index of the last row will be written in R_bottom ; the index of the first column will be written in R_left ; and the index of the last column will be written in R_right . If the cell file contains no cells, all four fields will be set to -1.

Code Display 19-2 Rectangle

typedef	struct {
	sword		R_left;		/* Index of first column written here. */
	sword		R_top;		/* Index of first row written here. */
	sword		R_right;		/* Index of last column written here. */
	sword		R_bottom;		/* Index of last row written here. */
} Rectangle;

GEOS SDK TechDocs

2.1 The CellFunctionParameters Structure

2.3 Actions on a Range of Cells