3 Generic C programming

Two tools are provided for generic C programming. Which one to use depends on the nature of the C source code:

• If the C source code contains functions that are designed to be called from Fortran using the macros in the f77.h header file provided by the CNF package, then the same GENERIC utility should be used that is used to process Fortran source file (described in the previous section).
• Otherwise the recipe described in the rest of this section should be used. Note that in this case we use the C preprocessor to create the necessary code, not the GENERIC utility. Clearly there are many ways to do this task, what is presented here is just a standardized method tuned for working with Starlink libraries.

First create your generic code routines. These actually go into an include file that is conventionally named with extension .cgen. There are several macros defined for use when defining generic functions.

• CGEN_BAD
• CGEN_FUNCTION
• CGEN_HDS_TYPE
• CGEN_MAX
• CGEN_MIN
• CGEN_PRM_TYPE
• CGEN_TYPE

You need to use CGEN_FUNCTION as part of the normal function declaration so that generic forms of the function name can be generated on inclusion. Each routine in a generic include file should start:

So a routine called kpg1_bad that returned an int and accepted a CGEN_CTYPE pointer, called value, would be defined as:

with the trivial job of testing the first element of an array against the BAD value constant.

The value of CGEN_TYPE will be set to the C type, that is double, float, int, short int, unsigned short int, char and unsigned char, as appropriate.

The value of CGEN_BAD will be set to one of the PRIMDAT constants VAL__BADD, VAL__BADR, VAL__BADI, VAL__BADW, VAL__BADUW, VAL__BADB or VAL__BADUB as appropriate, and the value of CGEN_HDS_TYPE will be set to the HDS type, one of _DOUBLE, _REAL, _INTEGER, _WORD, _UWORD, _BYTE or _UBYTE.

Now create a C file to includes the generic code. The include file is included once for each of the data types you want to support (this file can also contain related non-generic code). To do this define the macro CGEN_CODE_TYPE to be one of the values:

which selects the data type. Then include the file cgeneric_defs.h followed by your generic include file, (called mygenerics.cgen in the following example):

when compiled this will generate code for double precision and integer versions of the generic functions defined in mygeneric.cgen.

When you want to call the generic forms of a function, the name you supply to the CGEN_FUNCTION macro has one of character codes D, F, I, W, UW, B, and UB appended. So for our example kpg1_bad, we have the two functions kpg1_badD and kpg1_badI.

See the comments in the include files for descriptions of the other macros.