next up previous
Next: Building C Applications
Up: THE NDF_ LIBRARY C INTERFACE
Previous: Conventions Used in the C Interface

Using the C Interface - a Few Peculiarities  

There are several small peculiarities of the C interface to the NDF_ library which arise from the fact that the library itself is implemented mainly in Fortran. You must be aware of these when writing software in C, otherwise your program may give unpredictable results (including crashing):

Initialisation.

By default, the NDF_ library depends on the main routine in your program being written in Fortran. This is because Fortran compilers generally arrange for certain initialisation steps to be performed in the main routine. If this does not happen (because the main routine is written in C) the library may malfunction. Typically, problems occur when updating NDF history information (see §[*]), so you might not recognise immediately that your application is affected. One solution is to write your main routine in Fortran. This routine need do no more than call a C function to do all the work, and facilities which allow Fortran to call C in a portable way are available in the CNF library (SUN/209). Note that applications written using the ADAM programming environment are automatically structured in this way, with a Fortran main routine, so that using the ``alink'' command to build your application (see §[*]) will avoid any difficulty.

However, to avoid problems in standalone (non-ADAM) applications which have a C ``main'' function, you MUST invoke the C-specific ndfInit initialisation function as follows, before using any other facilities from the NDF_ library:

#include "ndf.h"                 /* Define NDF interface */
#include "sae_par.h"             /* Define SAI__OK */

int main( int argc, char *argv[] ) {
   int status = SAI__OK;

/* Initialise the NDF_ library for use from a C main routine. */
   ndfInit( argc, argv, &status );

   ...

}

Note that you should pass to ndfInit the argument count and argument vector which the operating system passes to your program via the standard arguments of the C ``main'' function. If, for any reason, this argument information is not accessible, then you should pass an argument count of zero (the argument vector is then ignored). This tells the NDF_ library that argument information is not available.

Input/output.

In general, it is not advisable to mix input/output (I/O) operations performed in C and Fortran on the same file within the same application. If you try to do so, you may find that output becomes jumbled. On input, you might also find that data get read several times, or maybe not at all.

This means that it is usually best to decide which language will perform I/O throughout your program and stick with that choice. Fortunately, the NDF_ library does not perform input and generates no significant output,[*] apart from error messages. However, it is designed to integrate with the MERS message and error reporting system (SUN/104), for example through its use of message tokens, and it uses MERS for reporting its own errors. MERS, in turn, uses Fortran to output these error messages (in ADAM applications it may also pass output to other tasks for delivery).

This means that if you are writing standalone software in C which calls the NDF_ library, then you should be able to use the standard I/O functions provided by C for most purposes quite safely, so long as you do so consistently. However, you should use MERS (or EMS, see SSN/4) for reporting errors, in order to be compatible with the error reporting performed by the NDF_ library.

In ADAM applications, you should always use MERS (or EMS) for both textual output intended for the user and error messages, otherwise output may be lost if the application is not run from the normal command line.



next up previous
Next: Building C Applications
Up: THE NDF_ LIBRARY C INTERFACE
Previous: Conventions Used in the C Interface


Starlink User Note 33
R.F. Warren-Smith
11th January 2000
E-mail:rfws@star.rl.ac.uk

Copyright © 2000 Council for the Central Laboratory of the Research Councils