Calling functions from C libraries

Note The notes in this section are for guidance only. UNICOM Systems, Inc. does not own the source code for functions in the C libraries and therefore cannot support them. If you have any problems, consult your C compiler reference guide.

The C runtime and maths libraries contain a number of general-purpose functions, some of which may be useful in Quantum programs. For example, if you want to square a number or calculate a square root, you will almost certainly find functions that do this in one of the C libraries.

Before you use a C function in Quantum, read the documentation on that function to find out what parameters it needs, and of what type. Having done this, you then need to provide this information in a format Quantum understands. This example uses the pow function which raises a value to a given power.

The UNIX documentation for pow( ) states that the function expects two arguments, both of which are double precision real variables. This means that your Quantum program must hold the value and the power (exponential) in x variables:

Even if one of the arguments is a constant, as both are in this example, you must assign the values to variables as Quantum will not accept real constants within the function’s parentheses.

pow( ) returns a value which you want to use in your Quantum program. In order to do this, you must define the function in the variables section of your run (that is, in the variables file or at the top of your program, before the ed statement). The function’s type must be set to the type of data the function returns. pow( ) returns a double precision value, so define it as:

The f at the end of the declaration means that pow is a function.

If cx(11,14) contains the value 12.5, the value of x3 will be 156.25.

C return type	Quantum return type
char	int
short	int
int	int
long	int
unsigned char	int
unsigned short	int
unsigned int	int
unsigned long	int
float	real
double	real

▪Quantum uses long integers, so all integer variable types except ‘unsigned long’ can be accommodated.

▪Quantum does not support unsigned values, but this is only a problem with ‘unsigned long’ variables.

If you are not interested in the value the function returns, or the function does not return a value at all, you can treat it as a subroutine and run it using call, as you would for the standard Quantum functions. For example:

displays the words ‘Print this text’.

Whether you call C library functions as subroutines or functions, you need to specify the arguments correctly in Quantum so that they are converted to the appropriate C variable types. In general, the safest option is to store any real or integer arguments in Quantum real or integer variables, as in the pow( ) example, and then call the function with those variables as the arguments. This is particularly important when dealing with Quantum data variables.

You can pass text strings as they are, as you saw for printf, but you cannot pass text held in data variables.

Note Quantum stores all names in lowercase. So if you want to reference an external function whose name includes uppercase characters, you need to define a function in private.c using a name in lowercase, to call the external function. For more information about private.c, see C subroutine code file.