(3M) Calculator User Manual

• error handling routines, which allow the user either to provide his own error
servicing routines, or to use the default routines pr ovided in the libScotch
distribution.
A MeTiS compa tibility library, called libscotchmetis.a, is also available. It
allows users who were pre viously using MeTiS in their software to take advantage of
the efficieny of Scotch without having to modify their code. The service s 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 free ing 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 er ror.
For instance, the SCOTCH
graphInit and SCOTCH graphLoad routines, described
in sections 7.5.1 and 7.5.4, re spectively, 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 dec lared in “stdio.h”,
this latter file must b e 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 ro utines of the libScotch
library.
7.1.2 Calling from Fortran
The routines of the libScotch library can also be ca lled from Fortran. For any C
function named SCOTCH
typeAction() which is documented in this manual, there
47