Editing Library Reference (section)

=Fortran 90 API=
The interface is accessed by including a <tt>use rsf</tt> statement in your program. The source code for the <tt>rsf</tt> module can be viewed  [http://rsf.svn.sourceforge.net/viewvc/rsf/trunk/api/f90/rsf.f90?view=markup in the repository]. A ('''G''') means that the entity was featured in the [[Guide_to_madagascar_API#Fortran-90_interface|Guide to API]].

==Constants==
For use with <tt>gettype</tt> and <tt>settype</tt>:
* <tt>sf_char</tt>=1
* <tt>sf_complex</tt>=4
* <tt>sf_float</tt>=3 ('''G''')
* <tt>sf_int</tt>=2
* <tt>sf_short</tt>=5
* <tt>sf_uchar</tt>=0

For use with <tt>sf_seek</tt>:
* <tt>sf_seek_set</tt>=0
* <tt>sf_seek_cur</tt>=1
* <tt>sf_seek_end</tt>=2

==Data types==
All procedures in Madagascar's F90 API act upon or take as input one of the following data types:
* <tt>axa</tt>: Holds some info about a hypercube axis (integer::n; real::o,d)
* <tt>file</tt>: Simply an interface to the <tt>sf_file</tt> type described in the C library.

==Functions==
Data types are indicated in ''italics'' and intent in '''''bold italics'''''. In the '''Wrapper for''' column, procedure names with no other description belong to the C library. The '''G?''' heading means "Demo-ed in the [[Guide_to_madagascar_API#Fortran-90_interface|Guide to the F90 API]]?".

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
| '''Name''' || '''Arguments''' || '''Result''' || '''What it does''' || '''Wrapper for''' || '''G?''' 
|-
| <tt>axisname</tt> || ''integer'' '''''in''''' <tt>i</tt>, optional ''character'' '''''in''''' <tt>mystring</tt> || ''character'' <tt>mystringi</tt> || Given a string <tt>mystring</tt> and a positive number <tt>i</tt>, this function will return the concatenation of the string and the number converted to string (<tt>mystringi</tt>). In practice, <tt>mystring</tt> will probably be "n", "o", "d", "label" or "unit", in preparation for writing to a header file. Default value for <tt>mystring</tt> is "n". || Verbose string operations in F90 || N
|-
| <tt>dimension</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''integer'' '''''out''''' <tt>dims</tt> || ''integer'' <tt>n</tt> || Returns number of dimensions of already-open file handle <tt>tag</tt> in <tt>n</tt>, and the dimension values in <tt>dims</tt> || <tt>sf_filedims</tt> || N
|-
| <tt>filesize</tt> || ''file'' '''''in''''' <tt>tag</tt>, optional ''integer'' '''''in''''' <tt>n</tt> || ''integer'' nr_elements || Computes number of <tt>n</tt>-dimensional subcubes in file hypercube. When <tt>n</tt> is absent, default is zero and the number of elements in file. || <tt>sf_filesize</tt>, <tt>sf_leftsize</tt>. || Y
|-
| <tt>gettype</tt> || ''file'' '''''in''''' <tt>tag</tt> || ''integer'' <tt>type</tt> || Reads the binary data type from the already-open file handle <tt>tag</tt>. The <tt>type</tt> constant should be then compared in the user-written code with one of the six type constants provided by the F90 interface || <tt>sf_gettype</tt> || Y
|-
| <tt>rsf_input</tt> || optional ''character'' '''''in''''' <tt>filename</tt> || ''file'' <tt>tag</tt> || Opens <tt>filename</tt> for reading and returns file handle <tt>tag</tt>. The default is <tt>filename</tt>="in", which corresponds to the standard input stream || <tt>sf_input</tt> || Y
|-
| <tt>rsf_output</tt> || optional ''character'' '''''in''''' <tt>filename</tt> || ''file'' <tt>tag</tt> || Opens <tt>filename</tt> for writing and returns file handle <tt>tag</tt>. The default is <tt>filename</tt>="out", which corresponds to the standard output stream || <tt>sf_input</tt> || Y
|}

==Subroutines==
Because subroutine names are preceded by a <tt>call</tt> statement, it is easy to find occurrences of them being used by typing: <bash>grep "call subroutine_name" {filt,user}/*/*.f90 user/*/*/*.f90</bash> in RSFSRC. 

Below, data types are indicated in ''italics'' and intent in '''''bold italics'''''. The type <i>multi</i> means that multiple data types can be used (subroutine is overloaded). In the '''Wrapper for''' column, procedure names with no other description belong to the C library. The '''G?''' heading means "Demo-ed in the [[Guide_to_madagascar_API#Fortran-90_interface|Guide to the F90 API]]?".

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
| '''Name''' || '''Arguments''' || '''What it does''' || '''Wrapper for''' || '''G?''' 
|-
| <tt>from_either</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''character'' '''''in''''' <tt>name</tt>, ''multi'' '''''out''''' <tt>value</tt>, optional ''multi'' '''''in''''' <tt>default</tt> || This subroutine looks for the real or integer variable <tt>name</tt> first in the history file, then in the parameter table. If it it is not found and <tt>default</tt> is present, it assigns it to <tt>value</tt>, otherwise it terminates the program. || <tt>sf_histint</tt>, <tt>sf_getint</tt> || N
|-
| <tt>from_par</tt> || optional ''file'' '''''in''''' <tt>tag</tt>, ''character'' '''''in''''' <tt>name</tt>, ''multi'' '''''out''''' <tt>value</tt>, optional ''multi'' '''''in''''' <tt>default</tt> || If already-opened file handle <tt>tag</tt> is supplied, then it reads into <tt>value</tt> a parameter designated by <tt>name</tt> from a history file. Else, it reads it from the parameter table. If the parameter is not found and a <tt>default</tt> is present, then that is used, else ends with failure. It can read from both history files and parameter tables the following types: integer, integer array, real. Strings can be read only from the history file, and not from the parameter table. Real arrays, logicals and logical arrays can be read only from the parameter table. || <tt>sf_histint</tt>, <tt>sf_getint</tt>, <tt>sf_histints</tt>, <tt>sf_getints</tt>, <tt>sf_histfloat</tt>, <tt>sf_getfloat</tt>, <tt>sf_histstring</tt>, <tt>sf_getfloats</tt>, <tt>sf_getbool</tt>, <tt>sf_getbools</tt> || Y
|-
| <tt>iaxa</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''axa'' '''''out''''' <tt>axisname</tt>, ''integer'' '''''in''''' <tt>axisnr</tt> || Read axis with number <tt>axisnr</tt> as axis <tt>axisname</tt> from the already-open file header indicated by <tt>tag</tt> || Multiple calls to F90 API's <tt>from_par</tt> || N
|-
| <tt>oaxa</tt> || ''file'' '''''in''''' <tt>tag,</tt> ''axa'' '''''in''''' <tt>axisname,</tt> ''integer'' '''''in''''' <tt>axisnr</tt> || Write axis <tt>axisname</tt> (i.e. its n, o, d) as axis with number <tt>axisnr</tt> to the already-open file header indicated by <tt>tag</tt> || Multiple calls to F90 API's <tt>from_par</tt> || N
|-
| <tt>raxa</tt> || ''axa'' '''''in''''' <tt>axisname</tt> || unformatted write to I/O unit nr. 0 (usually stdout, but system-dependent) of the contents of the <tt>axisname</tt> structure (n, o, d) || F90 write statement || N
|-
| <tt>rsf_read</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''multi'' '''''out''''' <tt>array</tt>, optional ''integer'' '''''in''''' <tt>n</tt> || If <tt>n</tt> is specified, the real or complex <tt>array</tt> must be 1-D and <tt>n</tt> elements will be read into it from an already-opened file specified by <tt>tag</tt>. If <tt>n</tt> is not specified, reads enough to fill the array, and the array can be 1-D, 2-D, 3-D, 4-D or 5-D. || <tt>sf_floatread</tt>, <tt>sf_complexread</tt> || Y
|-
| <tt>rsf_write</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''multi'' '''''in''''' <tt>array</tt>, optional ''integer'' '''''in''''' <tt>n</tt> || If <tt>n</tt> is specified, real or complex <tt>array</tt> must be 1-D and <tt>n</tt> elements will be written to an already-opened file specified by <tt>tag</tt>. If <tt>n</tt> is not specified, writes to file the entire contents of the array, and the array can be 1-D, 2-D, 3-D, 4-D or 5-D || <tt>sf_floatwrite</tt>, <tt>sf_complexwrite</tt> || Y
|-
| <tt>settype</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''integer'' '''''in''''' <tt>file_type</tt> || Write a type for the binary data to the already-open file header indicated by <tt>tag</tt>. Data type constants are also provided by the F90 API. || <tt>sf_settype</tt> || N
|-
| <tt>to_par</tt> || ''file'' '''''in''''' <tt>tag</tt>, ''character'' '''''in''''' <tt>name</tt>, ''multi'' '''''in''''' <tt>value</tt> || Writes <tt>name=value</tt> to already-opened file specified by <tt>tag</tt>. Value can be integer, integer array, real or character. || <tt>sf_putint</tt>, <tt>sf_putints</tt>, <tt>sf_putfloat</tt>, <tt>sf_putstring</tt> || N
|}

==Functions from the C library==
Functions from the C library for which an interface has been defined at the end of <tt>RSFSRC/api/f90/fortran.c</tt> can be called directly from Madagascar F90 programs. The programmer must know, however, that '''an argument type mismatch will result in a silent failure, with no informative errors.''' There may be other sources of problems as well. Caution therefore must be advised when calling these functions. The reason for these issues is that [http://people.scs.fsu.edu/~burkardt/f_src/mixed/mixed.html if a FORTRAN90 routine needs to pass a scalar parameter to a C routine, there is no standard way to ensure that a value is passed rather than an address]. The success rate of calling C from Fortran [http://w3.pppl.gov/~dmccune/papers-reports/linux_f90.txt is compiler-dependent] and [http://www.cs.sandia.gov/Zoltan/ug_html/ug_fortran.html special types may have to be defined for portability]. If you do have to call a C function from F90, follow the examples of the functions below. Use the C library reference to find argument and output types. A C-to-F90 data type dictionary follows:
{| class="wikitable" align="center" cellspacing="0" border="1"
! style="background:#ffdead;" | C ||! style="background:#ffdead;" | F90
|-
| RSFFILE || type(file)
|-
| INT || integer
|-
| OFFSETT || integer(kind=OFFKIND)
|}
===Void-output functions callable as subroutines===
These can be treated as subroutines, and accessed with a <tt>call</tt> statement. Follow 
* <tt>sf_error</tt> ('''G''') 
* <tt>sf_init</tt> ('''G''') ('''''Can it also be called in subroutines if we want to isolate I/O operations there?''''')
* <tt>sf_seek</tt>

===Non-void-output functions===
It is a good idea to declare in your program the function output type and use the keyword <tt>external</tt>, i.e.:
<pre>real, external :: sf_dosomething</pre>
Alternately, you may define a F90 <tt>interface</tt> block for the procedure(s). 

Several examples can be found in <tt>RSFSRC/filt/lib/rsf.f90</tt>, but they are not enumerated here because F90 wrappers exist for them and they should be used instead of the direct calls to the C library functions.