[Prev] [Next] [Top] [Bottom] [Contents] (8 out of 9)

FUNC Objects

A FUNC Object is used to define how developer-defined functions can be used in conjunction with a CGI. Data is provided to a FUNC Object as Argument strings. What the function does is up to the developer.

An existing function must be wrapped in order to be described by a FUNC Object. The wrapping consists of:

  1. Extracting argument data from the pSgeWorkCallData structure and passing it to the wrapped function.
  2. Converting returned data from the wrapped function and adding it to the pSgeWorkCallData structure.

How FUNC Objects are Managed

FUNC objects are saved on your hard disk using a naming convention described below. Sapphire/Web needs to know where to read and write FUNC Objects at start-up. If the environment variable DSQLDIR is set to point to a directory path, Sapphire/Web will look in that path. The DSQLDIR environment variable is useful for sharing FUNC Objects between multiple developers.

If the DSQLDIR environment variable is not set, Sapphire/Web will look in the project's directory.

FUNC Object Naming Convention

FUNC Objects are saved using the following naming conventions:

FUNC,FUNC,object_name,U
where

object_name
is the name of the FUNC Object
U
Data Object Type

How to Create FUNC Objects

To create a FUNC Object, use the Object Editor. See the section on the Object Editor for more information.

Components of a func Object

A FUNC Object describes the executable that is to be manipulated. It describes input to the executable and output from the executable. Several things must be specified in order to define a FUNC Object:

FUNC Object Options

When creating FUNC Objects, Options can be specified in the Options Editor. These Options fine tune the behavior of the FUNC Object. The following is a table of FUNC Object Options.

Extracting Data Object Arguments

There are several API calls that facilitate retrieving FUNC Object Argument information from the pSgeWorkCallData structure that gets passed to it. The prototype fora FUNC object function is as follows:

int function(pSgeWorkCallData p)

Example of Extracting Arguments:

/* Unknown number of Arguments */
size = SaReqGetNumArgs(p);
for(i = 0; i < size; i++) {
	value = SaReqGetNArg(p, i); /* value of Nth argument */
	name = SaReqGetNArgName(p, i); /* name of Nth argument */
	printf("%s=%s\n", name, value); /* print out argument */
}
...

/* Known Argument List of Filename and Filesize */
char *fname;
int size;
fname = SaReqGetArgByName(p, "Filename");
size = atoi(SaReqGetArgByName(p, "Filesize"));
...

Example of Adding Results:

char results[2][5];
int i, j, status;

status = my_func(results);
for(i = 0; i < 2; i++) {
	for(j = 0; j < 5; j++) {
		SaReqAppendString(p, results[i][j]);
	}
}
SaReqSetGroupCount(p, 1); /* number of groups is 1 */
SaReqAppendRowCount(p, 2); /* number of rows returned */
SaReqAppendColCount(p, 5); /* number of columns per row */

/* These do not need to be set, but are a way of sending 
other information back to the Object Binding code. */
SaReqSetErrorCode(p, 0); /* no error */
SaReqSetReturnCode(p, status); /* return status of my_func*/
SaReqSetAffectedRowCount(p, 2); /* set affected rows */


[Prev] [Next] [Top] [Bottom] [Contents] (8 out of 9)