CCB()

#define CCB(return_type, pointer_name, args) \
        return_type _cdecl (*pointer_name) args

This macro is useful for declaring pointers to functions that use the C calling conventions. For example, to declare a pointer to a function which is passed two strings and returns an integer, one could write

CCB(int, func_ptr, (const char *, const char *));

which would be expanded to

int _cdecl (*func_ptr) (const char *, const char *);

Different compilers have different syntax for the _cdecl keyword. Using this macro makes your callback compiler-independent.

See Also: PCB().

CellDeref()

void *	CellDeref(
        optr		CellRef);

This routine translates an optr to a cell into the cell's address. The routine is simply a synonym for LMemDeref() .

Include: cell.h

CellDirty()

void	CellDirty(
        void *		ptr);		/* pointer to anywhere in locked cell */

This routine marks a cell as "dirty"; i.e., the cell will have to be copied from memory back to the disk.

Include: cell.h

Tips and Tricks: All the cells in an item block are marked dirty at once; thus, you can call this routine just once for several cells in the same item block. Only the segment portion of the pointer is significant; thus, you can pass a pointer to anywhere in the cell. This is useful if you have incremented the pointer to the cell.

CellGetDBItem()

DBGroupAndItem 	CellGetDBItem(
        CellFunctionParameters *			cfp,
        word		row,			/* Get handles of cell in this row */
        byte		column);			/*...and this column */

All cells are stored as ungrouped DB items. If you wish to manipulate the cells with standard DB routines, you will need to know their handles. The routine is passed the address of the CellFunctionParameters and the row and column indices of the desired cell. It returns the DBGroupAndItem value for the specified cell. If there is no cell at the specified coordinates, it returns a null DBGroupAndItem . The routine does not lock the cell or change it in any way.

Include: cell.h

See Also: DBGroupAndItem.

CellGetExtent()

void	CellGetExtent(
        CellFunctionParameters *cfp,
        RangeEnumParams 		*rep); /* write boundaries in REP_bounds field */

This routine returns the boundaries of the utilized portion of the cell file. The routine is passed the address of the cell file's CellFunctionParameters structure.) It writes the results into the REP_bounds field of the passed RangeEnumParams structure. The index of the first row to contain cells is written into REP_bounds.R_top ; the index of the last occupied row is written to REP_bounds.R_bottom ; the index of the first occupied column is written to REP_bounds.R_left ; and the index of the last occupied row is written to REP_bounds.R_right . If the cell file contains no cells, all four fields will be set to -1..

Include: cell.h

CellLock()

void *	CellLock(
        CellFunctionParameters*			cfp,
        word			row,			/* Lock cell in this row... */
        word			column);			/* ... and this column */

This routine is passed the address of the CellFunctionParameters of a cell file, and the row and column indices of a cell. It locks the cell and returns a pointer to it.

Include: cell.h

See Also: CellLockGetRef().

CellLockGetRef()

void *	CellLockGetRef(
        CellFunctionParameters*			cfp,
        word			row,			/* Lock cell in this row... */
        word			column,			/* ... and this column */
        optr *			ref);			/* Write handles here */

This routine is passed the address of the CellFunctionParameters of a cell file, and the row and column indices of a cell. It locks the cell and returns a pointer to it. It also writes the locked cell's item-block and chunk handles to the optr. If the cell moves (e.g. because another cell is allocated), you can translate the optr structure into a pointer by passing it to CellDeref() .

Include: cell.h

Warnings: The optr becomes invalid when the cell is unlocked.

See Also: CellGetDBItem()., CellLock().

CellReplace()

void	CellReplace{
        CellFunctionParameters *			cfp,
        word		row,		/* Insert/replace cell at this row... */
        word		column,			/* ... and this column */
        const void *		cellData,			/* Copy this data into the new cell */
        word		size);			/* Size of new cell (in bytes) */

This routine is used for creating, deleting, and replacing cells in a cell file. To create or replace a cell, set cellData to point to the data to copy into the new cell, and set size to the length of the cell in bytes, and row and column the cell's coordinates. (As usual, cfp is a pointer to the cell file's CellFunctionParameters structure.) Any pre-existing cell at the specified coordinates will automatically be freed, and a new cell will be created.

To delete a cell, pass a size of zero. If there is a cell at the specified coordinates, it will be freed. (The cellData argument is ignored.)

Include: cell.h

Warnings: If a cell is allocated or replaced, pointers to all ungrouped items (including cells) in that VM file may be invalidated. The CellFunctionParameters structure must not move during the call; for this reason, it may not be in an ungrouped DB item. Never replace or free a locked cell; if you do, the cell's item block will not have its lock count decremented, which will prevent the block from being unlocked.

CellUnlock()

void	CellUnlock(
        void *	ptr); /* pointer to anywhere in locked cell */

This routine unlocks the cell pointed to by ptr . Note that a cell may be locked several times. When all locks on all cells in an item-block have been released, the block can be swapped back to the disk.

Include: cell.h

Tips and Tricks: The DB manager does not keep track of locks on individual items; instead, it keeps a count of the total number of locks on all the items in an item-block. For this reason, only the segment address of the cell is significant; thus, you can pass a pointer to somewhere within (or immediately after) a cell to unlock it. This is useful if you have incremented the pointer to the cell.

Be Sure To: If you change the cell, dirty it (with CellDirty() ) before you unlock it.