4.1 Developer's Interface

The Developer's Interface is second only to MetCal as an avenue by which to access the SPA. This interface makes the job of developing routines almost enjoyable by relieving the developer from the tedious job of building an interface program. The basic steps involved in beginning a new development are:

1. Open a working directory and load template files and configurations;
2. Extract associated subprograms from the archive for verification of their functionality;
3. Determine dependencies and create a build environment (Makefile);
4. Write a new routine and interface through the template file; and,
5. Compile and test your new code.

`spaopen'

This utility completes Step 1 above, by creating a working directory and pre-loading it with the desired template and configuration files. spaopen accepts an optional flag and a single argument. The argument is the root name of the subdirectory, to which will be appended _f90. This is a hold-over from the FORTRAN77 days of the archive, but serves to emphasize the development directory nicely, so it stays. The recognized flags are: -gui which loads the GUI driven template, and a copy of the MetCal source code into the working directory; -obs which loads an observational-file handler template into the working directory; -inv which loads a PV inversion example and test program into the working directory; and, -composite which loads a compositing-ready template into the new directory (see for a description of program templates). Running spaopen without a flag (but still with the directory name) will result in a directory containing the standard interface template, and is the common usage of the utility.

`spalist'

This utility allows the developer to look at a listing of the source code available in the SPA. The options for this tools are subroutines, functions, interfaces, and/or modules (templates may also work, but is of little practical use). These options of course refer to the subroutines of the archive. See Structure of the spa, for a complete description of the archive's structure. The ability to list the existing source is useful in two ways. Firstly, it allows you to ensure that there is no repetition of subprogram names in your development, and secondly it provides information on the algorithms already coded in the SPA but not explicitly referenced (inasmuch as the subprogram names provide useful information about the functionality of the source).

`spainfo'

This tool allows the developer to obtain detailed information about the functionality and interface of the specific routines listed as command line arguments. As of MetCal/SPA v1.3.9, the subprogram name can be given with or without suffixes (i.e. .f90) or prefixes (i.e. sub_, func_ or mod_). The name of the subprogram is enough to have spainfo extract the appropriate header information. A file header, contained in the source, is printed to STDOUT and contains package, interface, version, and functionality information. There are two primary uses for spainfo. The first is to scan the archive for pre-existing routines which may be of interest to you. The second is in interfacing to pre-existing routines, since a full list of the arguments and their properties are displayed in the header. Note that spainfo produces a warning message if it finds a generic subprogram.

`spaextract'

Moving onto Step 2 above, the spaextract utility allows the user to obtain source from the correct archive subdirectory. Any number of routines can be obtained simultaneously. Again, the full file name must be provided so that spaextract knows where to look in the archive for the required source. Since MetCal/SPA v1.3.9, this restriction has been relaxed. The subprogram name is now all that is required, with the prefix (i.e. sub_, func_ or mod_) and the suffix (i.e. .f90) now optional for additional extraction speed. Generic subprogram names are parsed before extraction and the user is alerted to the name of the file imported to the working directory.

`comp90.d'

Creating the build environment for your development project has never been easier. The comp90.d developer's interface tool allows the developer to painlessly develop a Makefile with a full dependency list and extract dependent files for recompilation in seconds (depending on the number of files to retrieve, of course). The only flag recognized by comp90.d is the -opt option, which compiles code in an optimized form. The compilation step can take quite a bit longer in this case, but optimization will yield returns at run time. comp90.d should be run any time that there is a modification to the source file listing of the directory so that all of its dependency lists are updated. Note that any SPA files that are automatically extracted by comp90.d are distribution cleanable. You should therefore run make distclean before re-running comp90.d in your working directory to clean out all of the automatically-retrieved code. Once the Makefile is built, it has the functionality of a standard GNU makefile.

The comp90.d utility requires some help in determining dependencies for function calls. If the source that you develop makes use of the functions foo and foo2, then your code should contain a line like:

     
     ! external :: foo,foo2

Although this is a comment line for the FORTRAN90 compiler, it will be correctly interpreted for the source's dependency list by comp90.d. The other anomaly associated with the comp90.d utility is the requirement of library loading, again displayed near the top of the template file:

     
     ! load FST       <- force comp90.d loading of ARMNLIB \
                                                 (FST library)
     ! load GEMPAK    <- force comp90.d loading of GEMLIB \
                                                 (GEMPAK library)
     ! load NCARG     <- force comp90.d loading of NCARG \
                                                 (NCAR Graphics library)

This will ensure that the proper libraries are loaded by the linker to create the executable. (Of course, only the `load XXXX' is required - the comments are optional). Note that NCARG loading is not standard in the template file.