Editing Guide to madagascar API (section)

==Fortran-77 interface==

The Fortran-77 clip function is listed below.
<syntaxhighlight lang="fortran">
	program Clipit
	implicit none
	integer n1, n2, i1, i2, in, out
	integer sf_input, sf_output, sf_leftsize, sf_gettype
	logical sf_getfloat, sf_histint
	real clip, trace(1000)

	call sf_init()
	in = sf_input("in")
	out = sf_output("out")

	if (3 .ne. sf_gettype(in)) 
     &  call sf_error("Need float input")

	if (.not. sf_histint(in,"n1",n1)) then
	   call sf_error("No n1= in input")
	else if (n1 > 1000) then
	   call sf_error("n1 is too long")
	end if
	n2 = sf_leftsize(in,1)

	if (.not. sf_getfloat("clip",clip)) 
     &  call sf_error("Need clip=")

	do 10 i2=1, n2
	   call sf_floatread(trace,n1,in)

	   do 20 i1=1, n1
	      if (trace(i1) >  clip) then
		 trace(i1)=clip
	      else if (trace(i1) < -clip) then
		 trace(i1)=-clip
	      end if
 20	   continue

	   call sf_floatwrite(trace,n1,out)
 10	continue

	stop
	end
</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="fortran">
	call sf_init()
</syntaxhighlight>

The program starts with a call to <tt>sf_init</tt>, which initializes the
command-line interface.
<syntaxhighlight lang="fortran">
	in = sf_input("in")
	out = sf_output("out")
</syntaxhighlight>

The input and output files are created with calls to
<tt>sf_input</tt> and <tt>sf_output</tt>. Because of the absence of
derived types in Fortran-77, we use simple integer pointers to
represent RSF files. Both <tt>sf_input</tt> and <tt>sf_output</tt>
accept a character string, which 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="fortran">
	if (3 .ne. sf_gettype(in)) 
     &  call sf_error("Need float input")
</syntaxhighlight>

RSF files can store data of different types (character, integer,
floating point, complex). The function <tt>sf_gettype</tt> checks the
type of data stored in the RSF file. We make sure that the type
corresponds to 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="fortran">
	if (.not. sf_histint(in,"n1",n1)) then
	   call sf_error("No n1= in input")
	else if (n1 > 1000) then
	   call sf_error("n1 is too long")
	end if
	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. Since Fortran-77 cannot
easily handle dynamic allocation, we also need to check that
<tt>n1</tt> is not larger than the size of the statically allocated
array. 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="fortran">
	if (.not. sf_getfloat("clip",clip)) 
     &  call 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="fortran">
	do 10 i2=1, n2
	   call sf_floatread(trace,n1,in)

	   do 20 i1=1, n1
	      if (trace(i1) >  clip) then
		 trace(i1)=clip
	      else if (trace(i1) < -clip) then
		 trace(i1)=-clip
	      end if
 20	   continue

	   call sf_floatwrite(trace,n1,out)
 10	continue
</syntaxhighlight>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Compiling===
To compile the Fortran-77 program, run
<pre>
f77 clip.f -L$RSFROOT/lib -lrsff -lrsf -lm
</pre>
Change <tt>f77</tt> to the Fortran 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>.