Scotch Brand 5.1.10 - Manual (Page 47)

• error handling routines, which allow the user either to provide his own error
servicing routines, or to use the default routines provided in the libScotch
distribution.
A MeTiS compatibility library, called libscotchmetis.a, is also available. It
allows users who were previously using MeTiS in their software to take advantage of
the efficieny of Scotch without having to modify their code. The services provided
by this library are described in Section 7.14.
7.1 Calling the routines of libScotch
7.1.1 Calling from C
All of the C routines of the libScotch library are prefixed with “SCOTCH ”. The
remainder of the function names is made of the name of the type of object to which
the functions apply (e.g. “graph”, “mesh”, “arch”, “map”, etc.), followed by the
type of action performed on this object: “Init” for the initialization of the object,
“Exit” for the freeing of its internal structures, “Load” for loading the object from
a stream, and so on.
Typically, functions that return an error code return zero if the function suc-
ceeds, and a non-zero value in case of error.
For instance, the SCOTCH graphInit and SCOTCH graphLoad routines, described
in sections 7.5.1 and 7.5.4, respectively, can be called from C by using the following
code.
#include <stdio.h>
#include "scotch.h"
...
SCOTCH_Graph
grafdat;
FILE * fileptr;
if (SCOTCH_graphInit (&grafdat) != 0) {
... /* Error handling */
}
if ((fileptr = fopen ("brol.grf", "r")) == NULL) {
... /* Error handling */
}
if (SCOTCH_graphLoad (&grafdat, fileptr, -1, 0) != 0) {
... /* Error handling */
}
...
Since “scotch.h” uses several system objects which are declared in “stdio.h”,
this latter file must be included beforehand in your application code.
Although the “scotch.h” and “ptscotch.h” files may look very similar on your
system, never mistake them, and always use the “scotch.h” file as the include file
for compiling a program which uses only the sequential routines of the libScotch
library.
7.1.2 Calling from Fortran
The routines of the libScotch library can also be called from Fortran. For any C
function named SCOTCH typeAction() which is documented in this manual, there
47