8 C Language Interface

To enable EMS to be used in C-only programs, without the need to link with Fortran libraries, it has now been implemented entirely in C. A C function equivalent exists for each of the Fortran EMS routines described in this document except EMS_FIOER which is specific to the Fortran language and has therefore been omitted.

The current naming scheme for the C functions (emsAnnuletc.) replaces the earlier one (ems_annul_c etc.), but the old names will still be recognised. There is no change to the argument lists. (See Appendix G for more details.)

Additional functions are available for C programmers:

• emsErrno( char const *token, int errval ) This will assign the message associated with a C errno (errval) to the specified token. Note that this is logically different from emsSyser; on UNIX they produce the same result but on other systems they may be different.
• int emsGtune( char const *key, int *status ) This returns the value of a tuning parameter. If differs from the Fortran version as the value is returned, not passed back by reference.
• emsSetnc( char const *token, char const *string, int maxchar ) This is similar to emsSetc but will limit the token length to maxchar characters. It must be used if string is not null-terminated. ems.h defines ems_setc_c to be equivalent to emsSetnc - there is no Fortran interface for this function.
• int emsStune( char const *key, int value, int *status ) This replaces the emsTune function. It returns the old value of the given parameter so that it can be re-established using another call to this function (this may be necessary for systems that do not share tuning values).

A full list of the C function prototypes is provided in Appendix G.

The function emsExpnd has the argument maxlen, not found in its equivalent Fortran call sequence. This argument represents the maximum allowable string length for the expanded message and is necessary for the use of returned C character strings where the declared length cannot be determined. Normally, the argument maxlen is given the global constant value EMS__SZMSG. There should be space for maxlen+1 characters in the output string.

The correspondence between ANSI Fortran 77 data types and ANSI C data types is not defined: i.e. it is implementation dependent. However, the most likely correspondence can be assumed and this has been coded into the C/Fortran interface. This correspondence is apparent from the C interface function prologues provided in Appendix G and is summarised in the following table:

Note that the interpretation of the int lvalue argument presented to the function emsSetl is that defined by the ANSI C language.