The Anatomy of the Population Callback Structure

Population Callback Prototype

The population callback function prototype is defined in include/WorkingDialog.h as:

typedef void (*PopulationCallback) SUTPROTO((
	void * 			wid, 
	void *			ClientData, 
	SaCallbackStruct			*data
	));

The SUTPROTO macro allows for compilation in ANSI as well as old K&R style. The parameters for a population callback are:

wid - Is not used.
ClientData - is the client data specified in the Results Detail Dialog
data - is a pointer to the callback data structure, SaCallbackStruct.

The data contained in the Callback Structure (SaCallbackStruct), is read-only and should not be modified.

The Callback Structure

The SaCallbackStruct structure is defined in include/WorkingDialog.h as:

typedef struct {
	int reason;
	XEvent *event;
	SaDataStruct *groups;
	int nGroups;
	} SaCallbackStruct;

The Fields in the SaCallbackStruct structure are:

reason - the return status of the Object Binding request
event - not used at this time. Its value is initialized to NULL
nGroups - specifies the number of groups of results data that was bound to this Data Site.
groups - is a pointer to an array of SaDataStruct structures of size nGroups. Each structure in the array represents one results group.

The Data Structure

The SaDataStruct structure is defined in include/WorkingDialog.h as:

typedef struct {
	char ***data;
	long nRows;
	int nCols;
	int *colWidth;
	int *maxColWidth;
	int *colCodes;
	int *colFormat;
	char **columnTitles;
	void *options;
} SaDataStruct;

The Fields in the SaCallbackStruct structure are:

data - a pointer to a two-dimensional array of strings (char*). Some of these string pointers can be NULL, so be careful when using calls such as strlen, strcat, etc., which don't handle NULL pointers.
nRows - the size of the first dimension of the data array. It is the number of rows contained in a results group.
nCols - the size of the second dimension of the data array. It is the number of columns in a result group's row.
colWidth - field is a pointer to an array of nCols integers. The size of the array is nCols. Each element is the maximum column width for that column over all rows.
maxColWidth - a pointer to an array of integers. The size of the array is nCols. Each element is the width of the column as specified by the meta data of the Data Object. Some data types such as int will have this set to -1.
colCodes - for future use
colFormat - for future use
columnTitles - an array of strings (char*) of size nCols. The values are the column titles as specified by the meta data of the Data Object.
options - for future use

Examples of Population Callbacks can be found in $SAPPHIRE/client/src/SaHtmlC.c.

[Top] [Prev] [Next] [Bottom] [Contents]

info@bluestone.com