Editing Guide to madagascar API (section)

==C interface==

The C clip function is listed below.
<syntaxhighlight lang="c">
/* Clip the data. */

#include <rsf.h>

int main(int argc, char* argv[])
{
    int n1, n2, i1, i2;
    float clip, *trace=NULL;
    sf_file in=NULL, out=NULL; /* Input and output files */

    /* Initialize RSF */
    sf_init(argc,argv);
    /* standard input */
    in = sf_input("in");
    /* standard output */
    out = sf_output("out");

    /* check that the input is float */
    if (SF_FLOAT != sf_gettype(in)) 
	sf_error("Need float input");

    /* n1 is the fastest dimension (trace length) */
    if (!sf_histint(in,"n1",&n1)) 
	sf_error("No n1= in input");
    /* leftsize gets n2*n3*n4*... (the number of traces) */
    n2 = sf_leftsize(in,1);

    /* parameter from the command line (i.e. clip=1.5 ) */
    if (!sf_getfloat("clip",&clip)) sf_error("Need clip=");

    /* allocate floating point array */
    trace = sf_floatalloc (n1);

    /* loop over traces */
    for (i2=0; i2 < n2; i2++) {

	/*read a trace */
	sf_floatread(trace,n1,in);

	/* loop over samples */
	for (i1=0; i1 < n1; i1++) {
	    if      (trace[i1] >  clip) trace[i1]= clip;
	    else if (trace[i1] < -clip) trace[i1]=-clip;
	}
    
	/* write a trace */
	sf_floatwrite(trace,n1,out);
    }

    free(trace);
    sf_close();
    exit(0);
}
</syntaxhighlight>

Let us examine it in detail. 
<syntaxhighlight lang="c">
#include <rsf.h>
</syntaxhighlight>

The include preprocessing directive is required to access the RSF interface. 
<syntaxhighlight lang="c">
    sf_file in=NULL, out=NULL; /* Input and output files */
</syntaxhighlight>

RSF data files are defined with an abstract <tt>sf_file</tt> data type. An
abstract data type means that the contents of it are not publicly declared,
and all operations on <tt>sf_file</tt> objects should be performed with
library functions. This is analogous to <tt>FILE *</tt> data type used in
<tt>stdio.h</tt> and as close as C gets to an object-oriented style of
programming (Roberts, 1998<ref>Roberts, E. S.,  1998, Programming abstractions in C: Addison-Wesley.</ref>).
<syntaxhighlight lang="c">
    /* Initialize RSF */
    sf_init(argc,argv);
</syntaxhighlight>

Before using any of the other functions, you must call
<tt>sf_init</tt>. This function parses the command line and
initializes an internally stored table of command-line parameters.
<syntaxhighlight lang="c">
    /* standard input */
    in = sf_input("in");
    /* standard output */
    out = sf_output("out");
</syntaxhighlight>

The input and output RSF file objects are created with <tt>sf_input</tt> and
<tt>sf_output</tt> constructor functions. Both these functions take a string
argument. The string may refer to a file name or a file tag. For example, if
the command line contains <tt>vel=velocity.rsf</tt>, then both
<tt>sf_input("velocity.rsf")</tt> and <tt>sf_input("vel")</tt> are
acceptable. Two tags are special: <tt>"in"</tt> refers to the file in the
standard input and <tt>"out"</tt> refers to the file in the standard
output. 
<syntaxhighlight lang="c">
    /* check that the input is float */
    if (SF_FLOAT != sf_gettype(in)) 
	sf_error("Need float input");
</syntaxhighlight>
 
RSF files can store data of different types (character, integer,
floating point, complex). We extract the data type of the input file
with the library <tt>sf_gettype</tt> function and check if it
represents floating point numbers. If not, the program is aborted with
an error message, using the <tt>sf_error</tt> function.  It is
generally a good idea to check the input for user errors and, if they
cannot be corrected, to take a safe exit.
<syntaxhighlight lang="c">
    /* n1 is the fastest dimension (trace length) */
    if (!sf_histint(in,"n1",&n1)) 
	sf_error("No n1= in input");
    /* leftsize gets n2*n3*n4*... (the number of traces) */
    n2 = sf_leftsize(in,1);
</syntaxhighlight>

Conceptually, the RSF data model is a multidimensional hypercube. By
convention, the dimensions of the cube are stored in <tt>n1=</tt>,
<tt>n2=</tt>, etc. parameters. The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> refers to the trace length. We extract it using the
<tt>sf_histint</tt> function (integer parameter from history) and
abort if no value for <tt>n1</tt> is found. We could proceed in a
similar fashion, extracting <tt>n2</tt>, <tt>n3</tt>, etc. If we are
interested in the total number of traces, like in the clip example, a
shortcut is to use the <tt>sf_leftsize</tt> function. Calling
<tt>sf_leftsize(in,0)</tt> returns the total number of elements in
the hypercube (the product of <tt>n1</tt>, <tt>n2</tt>, etc.), calling
<tt>sf_leftsize(in,1)</tt> returns the number of traces (the product
of <tt>n2</tt>, <tt>n3</tt>, etc.), calling
<tt>sf_leftsize(in,2)</tt> returns the product of <tt>n3</tt>,
<tt>n4</tt>, etc. By calling <tt>sf_leftsize</tt>, we avoid the need
to extract additional parameters for the hypercube dimensions that we
are not interested in.
<syntaxhighlight lang="c">
    /* parameter from the command line (i.e. clip=1.5 ) */
    if (!sf_getfloat("clip",&clip)) sf_error("Need clip=");
</syntaxhighlight>
 
The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. The parameter has the
<tt>float</tt> type, therefore we read it with the
<tt>sf_getfloat</tt> function. If no <tt>clip=</tt> parameter is
found among the command line arguments, the program is aborted with an
error message using the <tt>sf_error</tt> function.
<syntaxhighlight lang="c">
    /* allocate floating point array */
    trace = sf_floatalloc (n1);
</syntaxhighlight>
 
Next, we allocate an array of floating-point numbers to store a trace
with the library <tt>sf_floatalloc</tt> function. Unlike the standard
<tt>malloc</tt> the RSF allocation function checks for errors and
either terminates the program or returns a valid pointer.
<syntaxhighlight lang="c">
    /* loop over traces */
    for (i2=0; i2 < n2; i2++) {

	/*read a trace */
	sf_floatread(trace,n1,in);

	/* loop over samples */
	for (i1=0; i1 < n1; i1++) {
	    if      (trace[i1] >  clip) trace[i1]= clip;
	    else if (trace[i1] < -clip) trace[i1]=-clip;
	}
    
	/* write a trace */
	sf_floatwrite(trace,n1,out);
    }
</syntaxhighlight>
 
The rest of the program is straightforward. We loop over all available
traces, read each trace, clip it and right the output out. The syntax
of <tt>sf_floatread</tt> and <tt>sf_floatwrite</tt> functions is
similar to the syntax of the C standard <tt>fread</tt> and
<tt>fwrite</tt> function except that the type of the element is
specified explicitly in the function name and that the input and
output files have the RSF type <tt>sf_file</tt>.

<syntaxhighlight lang="c">
sf_close();
exit(0)
</syntaxhighlight>

We explicitly close the input file to avoid leaving a stale temporary file in <tt>$DATAPATH</tt> if the program is called in a pipe sequence. Then, we close the program by sending the shell the Unix code that tells it no errors were encountered. 

Note that this is an introductory example, optimized for clarity, not execution speed. For advanced techniques, see [[Madagascar Code Patterns]].

===Compiling===
To compile the <tt>clip</tt> program, run
<pre>
cc clip.c -I&#36;RSFROOT/include -L&#36;RSFROOT/lib -lrsf -lm
</pre>
Change <tt>cc</tt> to the C compiler appropriate for your system and include
additional compiler flags if necessary. The flags that RSF typically uses are
in <tt>&#36;RSFROOT/share/madagascar/etc/config.py</tt>.