[Prev] [Next] [Top] [Bottom] [Contents] (2 out of 4)

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.
Note: 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
Note: Examples of Population Callbacks can be found in $SAPPHIRE/client/src/SaHtmlC.c.


[Prev] [Next] [Top] [Bottom] [Contents] (2 out of 4)