Writing Custom Functions

In addition to using Production Reporting’s built-in functions, you can write your own functions in C using the supplied source file UFUNC.C (or EXTUFUNC.C on Windows). If the C routine accesses a C++ routine, rename the file to UFUNC.CPP. (This enables the C++ compiler to recognize that it is a C++ source file.) The supplied UFUNC.C source file is compatible with both C and C++ compilers.

You can pass any number if arguments to your function. Values can be returned by the function or passed back in variables. Arguments and return values can either be numeric, single byte character strings, or UTF-8 encoded character strings. The specifics on how to specify the various argument and return types are explained in the UFUNC.C module. When using UTF-8 encoded strings, set UseUnicodeInternal=TRUE in SQR.INI.

After editing and recompiling the UFUNC.C module, you must recreate the Production Reporting executables. For UNIX, execute the sqrmake script located in the lib directory. For Windows, use the sqrext.mak make file located in the lib directory to recreate the DLL module.

When adding a new user-defined function to UFUNC.C, follow these rules:

For routines that return a string value, define the routine to take the following arguments:
- (int) Number of arguments
- (char *) or (double *) Array of argument pointers, to either char[] or double.
- (char *) Address of the result string. If unchanged, the function returns a NULL string.
- (int) Maximum length of the result string, in bytes.
For routines that return a numerical value, define the routine to take the following arguments:
- (int) Number of arguments
- (char *) or (double *) Array of argument pointers, to either char[] or double.
- (double *) Address of the result value. If unchanged, the function returns a zero.

Following is an example of how to add a user-defined function to Production Reporting so that is can be invoked using LET, IF, or WHILE. The example adds a new function called rand, which returns a random number. The function accepts a single parameter used as the seed to start a new sequence of numbers. If the seed is zero, the same sequence is used.

To add the rand function to the UFUNC.C module, make the following modifications:

Add the prototype for the function.

LINKAGE void sqr_ufunc_rand CC_ARGS((int, double *[], double *));

Add the function name to the declaration table.

The name in the table must be in lower case; however, you can reference it in either upper case or lower case in your Production Reporting program.
The name of the function called from Production Reporting is rand.
The return type is n for numeric, the number of arguments is “1”, and the argument type is n for numeric.
The function name in the UFUNC.C module is sqr_ufunc_rand.

You must enter the characters “PVR” before the function name.

Name	Return_Type	Number of Arguments	Arg_Types	Function
{(char *)"max",	'n',	0,	(char *)"n",	PVR sqr_ufunc_max},
{(char *)"split",	'n',	0,	(char *)"C",	PVR sqr_ufunc_split},
{(char *)"printarray",	'n',	4,	(char *)"cnnc",	PVR sqr_ufunc_printarray},
{(char *)"system",	'n',	1,	(char *)"c",	PVR sqr_ufunc_sys},
{(char *)"sleep",	'n',	1,	(char *)"n",	PVR sqr_ufunc_sleep},
{(char *)"rand",	'n',	1,	(char *)"n",	PVR sqr_ufunc_rand},
{(char *)"unitest",	'u',	2,	(char *)"uU",	PVR sqr_ufunc_unitest},
/* Last entry must be NULL -- do not change / {(char )"", '\0', 0, (char *)"", 0}

At the end of the UFUNC.C module add the sqr_ufunc_rand routine.

/*
 * RandNumb function -- Get random number and optionally set seed
 *
 * Usage:  LET #Number = rand(#Seed)
 *
*/
LINKAGE void sqr_ufunc_rand CC_ARGL((argc, argv, result))
CC_ARG(int, argc)		/* Number of actual arguments */
CC_ARG(double *, argv[])	/* Pointers to arguments */
CC_LARG(double *, result)	/* Where to store result */
   {
#if defined(UNIX)
   if (*argv[0] > 0)		/* If seed > 0 then set it */
        srand48((unsigned int)*argv[0]);
   *result = drand48();	/* Get random number */
#else
   if (*argv[0] > 0)
        srand((unsigned int)*argv[0]);
   *result = (double)rand()/(double)(RAND_MAX);
#endif
   return;
   }

After you make these modifications, compile the UFUNC.C module and recreate the Production Reporting executables.

The following is an example of a simple Production Reporting program that uses the newly added function:

BEGIN-PROGRAM
  DO Get-Random-Number
  DO Process-Calculations
END-PROGRAM

BEGIN-PROCEDURE Get-Random-Number
  LET #Seed = 44
  LET #Ran = RAND(#Seed)
END-PROCEDURE

BEGIN-PROCEDURE Process-Calculations
  .
  .
  .
END-PROCEDURE