Below is a simple example of a source file containing C formula operators:
#include "cexits.h"
void f_multiply(result,first,second)
double *result, *first, *second;
{
/* Function to multiply two numbers */
*result = *first * *second;
set_scale(para_scale(1) + para_scale(2));
set_occurs(1);
}
/**/
void f_unittoword(word,number1,number2)
char *word;
double *number1, *number2;
/* cannot use integer parameters */
{
/* Function to convert a numeral to a word */
int i;
static char *word_for_nr[] =
{
"Zero","One","Two","Three","Four",
"Five","Six","Seven","Eight","Nine"
};
strcpy(word,word_for_nr[(int) *number1]);
set_occurs(5);
}
|
The source file can contain any number of functions. It must include the file cexits.h, which is supplied with DP4.
The major points to consider are the function name, the parameters and the use of macros such as set_scale and para_scale. These topics are covered in detail in the following sections.
The function name is the same as the C function defined in the Program Editor, in lowercase and prefixed with f_.
The use of the f_ prefix avoids clashes with existing library functions. However, if you wish to change or delete the prefix, you can edit maps 40 to 43 of the mapset, PROG2C, on the SYSTEM database. These maps are used by the Program Compiler to generate the C Function interface.
The function should be of type void.
Example:
Consider a C formula operator defined as MULTIPLY from the C Function definition option in the Program Editor. The C function in the source code is defined as: void f_multiply().
A QA Build program passes parameters as values when it calls a C formula operator, but the C function itself accesses parameters as pointers. The first parameter of the C function is used for the return value of the formula operator. The second and the third parameters of the C function correspond to the first and second parameters of the formula operator respectively.
The pointers that are received by a C function do not point to the original data item within QA Build but point to items on QA Build's internal stack.
The allowable parameter types are listed in the table of Function Datatypes .
For all return fields you must set the number of occurs, even if it is only 1. For all numerical return fields, you must set the scale factor. These operations can be performed using special macros which are defined in CEXITS.H. In addition, there are macros to obtain the same properties from the parameters sent.
If you want to pass more than two parameters from a C formula operator you must use a macro to obtain an address pointer. You can then use other macros in the same way as for the first two parameters.
| Macro | When to Use | Explanation |
|---|---|---|
| set_occurs(occurs) | Returning a value | Sets the number of occurs of the return field. For example, to set the number of occurs to 5: set_occurs(5); |
| Returning a numerical field | Sets the scale factor of the return field. For example, to set the scale factor to 2: set_scale(2); | |
| para_occurs(para_nr) | Passing multi-occurs parameters | Obtains the number of occurs of a specified parameter. For example, to obtain the number of occurs of the first parameter: value = para_occurs(1); |
| para_scale(para_nr) | Passing numerical parameters | Obtains the scale factor of a specified parameter. For example,to obtain the scale factor of the2nd parameter: value = para_scale(2) |
| Passing more than two parameters | Obtains the address of a specified parameter. For example, to obtain the pointer of the 3rd parameter: p_para3 = para_address(3); |
The macros set_occurs() and set_scale() must be called after all other data operations in the function, as they can otherwise have undesirable side effects.