\title{Guide to RSF API}\email{sergey.fomel@beg.utexas.edu}\author{Sergey Fomel}\lefthead{Fomel}\righthead{RSF API}\maketitle\begin{abstract}  This guide explains the RSF programming interface.\end{abstract}\section{Introduction}To work with RSF files in your own programs, you may need to use anappropriate programming interface. We will demonstrate the interface indifferent languages using a simple example. The example is a clipping program.It reads and writes RSF files and accesses parameters both from the input fileand the command line. The input is processed trace by trace. This is notnecessarily the most efficient approach\footnote{Compare with the \href{http://svn.sourceforge.net/viewcvs.cgi/rsf/trunk/filt/proc/Mclip.c?view=markup}{library clip program}.} but it suffices for a simple demonstration.\section{C interface}\lstset{language=c,numbers=left,numberstyle=\tiny,showstringspaces=false}The C clip function is listed below.\lstinputlisting[frame=single]{\RSF/api/clip.c}Let us examine it in detail. \lstinputlisting[firstline=3,lastline=3,frame=single]{\RSF/api/clip.c}The include preprocessing directive is required to access the RSF interface. \lstinputlisting[firstline=9,lastline=9,frame=single]{\RSF/api/clip.c}RSF data files are defined with an abstract \texttt{sf\_file} data type. Anabstract data type means that the contents of it are not publicly declared,and all operations on \texttt{sf\_file} objects should be performed withlibrary functions. This is analogous to \texttt{FILE *} data type used in\texttt{stdio.h} and as close as C gets to an object-oriented style ofprogramming \cite[]{cbook}.\lstinputlisting[firstline=11,lastline=12,frame=single]{\RSF/api/clip.c}Before using any of the other functions, you must call\texttt{sf\_init}. This function parses the command line andinitializes an internally stored table of command-line parameters.\lstinputlisting[firstline=13,lastline=16,frame=single]{\RSF/api/clip.c}The input and output RSF file objects are created with \texttt{sf\_input} and\texttt{sf\_output} constructor functions. Both these functions take a stringargument. The string may refer to a file name or a file tag. For example, ifthe command line contains \texttt{vel=velocity.rsf}, then both\texttt{sf\_input("velocity.rsf")} and \texttt{sf\_input("vel")} areacceptable. Two tags are special: \texttt{"in"} refers to the file in thestandard input and \texttt{"out"} refers to the file in the standardoutput. \lstinputlisting[firstline=18,lastline=20,frame=single]{\RSF/api/clip.c} RSF files can store data of different types (character, integer,floating point, complex). We extract the data type of the input filewith the library \texttt{sf\_gettype} function and check if itrepresents floating point numbers. If not, the program is aborted withan error message, using the \texttt{sf\_error} function.  It isgenerally a good idea to check the input for user errors and, if theycannot be corrected, to take a safe exit.\lstinputlisting[firstline=22,lastline=26,frame=single]{\RSF/api/clip.c}Conceptually, the RSF data model is a multidimensional hypercube. Byconvention, the dimensions of the cube are stored in \texttt{n1=},\texttt{n2=}, etc. parameters. The \texttt{n1} parameter refers to thefastest axis. If the input dataset is a collection of traces,\texttt{n1} refers to the trace length. We extract it using the\texttt{sf\_histint} function (integer parameter from history) andabort if no value for \texttt{n1} is found. We could proceed in asimilar fashion, extracting \texttt{n2}, \texttt{n3}, etc. If we areinterested in the total number of traces, like in the clip example, ashortcut is to use the \texttt{sf\_leftsize} function. Calling\texttt{sf\_leftsize(in,0)} returns the total number of elements inthe hypercube (the product of \texttt{n1}, \texttt{n2}, etc.), calling\texttt{sf\_leftsize(in,1)} returns the number of traces (the productof \texttt{n2}, \texttt{n3}, etc.), calling\texttt{sf\_leftsize(in,2)} returns the product of \texttt{n3},\texttt{n4}, etc. By calling \texttt{sf\_leftsize}, we avoid the needto extract additional parameters for the hypercube dimensions that weare not interested in.\lstinputlisting[firstline=28,lastline=29,frame=single]{\RSF/api/clip.c} The clip parameter is read from the command line, where it can bespecified, for example, as \texttt{clip=10}. The parameter has the\texttt{float} type, therefore we read it with the\texttt{sf\_getfloat} function. If no \texttt{clip=} parameter isfound among the command line arguments, the program is aborted with anerror message using the \texttt{sf\_error} function.\lstinputlisting[firstline=31,lastline=32,frame=single]{\RSF/api/clip.c} Next, we allocate an array of floating-point numbers to store a tracewith the library \texttt{sf\_floatalloc} function. Unlike the standard\texttt{malloc} the RSF allocation function checks for errors andeither terminates the program or returns a valid pointer.\lstinputlisting[firstline=34,lastline=48,frame=single]{\RSF/api/clip.c} The rest of the program is straightforward. We loop over all availabletraces, read each trace, clip it and right the output out. The syntaxof \texttt{sf\_floatread} and \texttt{sf\_floatwrite} functions issimilar to the syntax of the C standard \texttt{fread} and\texttt{fwrite} function except that the type of the element isspecified explicitly in the function name and that the input andoutput files have the RSF type \texttt{sf\_file}.\subsection{Compiling}To compile the \texttt{clip} program, run\begin{verbatim}cc clip.c -I$RSFROOT/include -L$RSFROOT/lib -lrsf -lm\end{verbatim}Change \texttt{cc} to the C compiler appropriate for your system and includeadditional compiler flags if necessary. The flags that RSF typically uses arein \texttt{\$RSFROOT/lib/rsfconfig.py}.\section{C++ interface}\lstset{language=c++}The C++ clip function is listed below.\lstinputlisting[frame=single]{\RSF/api/clip.cc}Let us examine it line by line. \lstinputlisting[firstline=4,lastline=4,frame=single]{\RSF/api/clip.cc}Including ``\texttt{rsf.hh}'' is required for accessing the RSF C++interface.\lstinputlisting[firstline=8,lastline=8,frame=single]{\RSF/api/clip.cc}A call to \texttt{sf\_init} is required to initialize the internally storedtable of command-line arguments.\lstinputlisting[firstline=10,lastline=11,frame=single]{\RSF/api/clip.cc}Two classes: \texttt{iRSF} and \texttt{oRSF} are used to define input andoutput files. For simplicity, the command-line parameters are also handled as an \texttt{iRSF} object, initialized with zero.\lstinputlisting[firstline=16,lastline=17,frame=single]{\RSF/api/clip.cc}Next, we read the data dimensions from the input RSF file object called\texttt{in}: the trace length is a parameter called ``\texttt{n1}'' and thenumber of traces is the size of \texttt{in} remaining after excluding thefirst dimension. It is extracted with the \texttt{size} method.\lstinputlisting[firstline=19,lastline=19,frame=single]{\RSF/api/clip.cc} The clip parameter should be specified on the command line, forexample, as \texttt{clip=10}. It is extracted with the \texttt{get}method of \texttt{iRSF} class from the \texttt{par} object.\lstinputlisting[firstline=21,lastline=21,frame=single]{\RSF/api/clip.cc}The trace object has the single-precision floating-point type and is a1-D array of length \texttt{n1}. It is declared and allocated usingthe \texttt{valarray} template class from the standard C++ library.\lstinputlisting[firstline=23,lastline=32,frame=single]{\RSF/api/clip.cc}Next, we loop through the traces, read each trace from \texttt{in}, clip itand write the output to \texttt{out}.\subsection{Compiling}To compile the C++ program, run\begin{verbatim}c++ clip.cc -I$RSFROOT/include -L$RSFROOT/lib -lrsf++ -lrsf -lm\end{verbatim}Change \texttt{c++} to the C++ compiler appropriate for your system andinclude additional compiler flags if necessary. The flags that RSF typicallyuses are in \texttt{\$RSFROOT/lib/rsfconfig.py}.\section{Fortran-77 interface}\lstset{language=fortran}The Fortran-77 clip function is listed below.\lstinputlisting[frame=single]{\RSF/api/clip.f}Let us examine it in detail.\lstinputlisting[firstline=8,lastline=8,frame=single]{\RSF/api/clip.f}The program starts with a call to \texttt{sf\_init}, which initializes thecommand-line interface.\lstinputlisting[firstline=9,lastline=10,frame=single]{\RSF/api/clip.f}The input and output files are created with calls to\texttt{sf\_input} and \texttt{sf\_output}. Because of the absence ofderived types in Fortran-77, we use simple integer pointers torepresent RSF files. Both \texttt{sf\_input} and \texttt{sf\_output}accept a character string, which may refer to a file name or a filetag. For example, if the command line contains\texttt{vel=velocity.rsf}, then both\texttt{sf\_input("velocity.rsf")} and \texttt{sf\_input("vel")} areacceptable. Two tags are special: \texttt{"in"} refers to the file inthe standard input and \texttt{"out"} refers to the file in thestandard output.\lstinputlisting[firstline=12,lastline=13,frame=single]{\RSF/api/clip.f}RSF files can store data of different types (character, integer,floating point, complex). The function \texttt{sf\_gettype} checks thetype of data stored in the RSF file. We make sure that the typecorresponds to floating-point numbers. If not, the program is aborted