Compiling and linking your code

In this section, you will learn how to compile your McIDAS-X source files, link object files, and store the object files in a library. You'll use the mccomp script to compile and link your code, and the mcar script to create and update libraries.

Compiling source files

The script mccomp provides a platform-independent compilation and linking environment for McIDAS-X source files. By recognizing source file extensions, mccomp can understand some of the compile options needed by some source files. For example, if the source file extension is .for, .fp, or .pgm, mccomp calls the Fortran compiler.

The mccomp script has four options that you will frequently use when compiling source files.

Option	Description
-c	compiles only
-Dval	sets preprocessor values
-g	produces symbol table for debugging
-Idir	searches a list of directories for include files

For example, to compile the source file program.pgm, use the mccomp script shown below. This script creates the object file program.o. The next section, Linking object files describes how to create the McIDAS-X command program.k.

Linking object files

Once the object file has been created, you must link the file with the necessary libraries to create the executable code. The mccomp script recognizes the platform's linking options, so you do not need to change link options when moving between platforms.

The table below lists three mccomp script options that you will frequently use for linking source files.

Option	Description
-Ldir	links the command with the a directory containing the libraries
--llibrary	links the command with a specified library
-obinary	specifies a name for the command created

To link the object file program.o created in the previous example to create program.k, run the script below.

Note that the script contains the object file main.o. McIDAS-X commands written in Fortran do not contain their own MAIN program. You must link the appropriate MAIN program from main.o.

Storing object files in a library

You may want to keep all your local functions in a local library. This makes software management much easier. Use the script mcar to put object files in a local library. The example below shows you how to compile the file foo.for and store the resulting object file in the library libdev.a.

If your projects contain several source files, you may want to use a project management utility such as make to compile your code. The Unix make utility uses a description file or makefile to construct a sequence of Unix commands that the Unix shell runs. This utility helps you generate your mccomp and mcar commands. If you are not familiar with the make utility, SSEC recommends the book Managing Projects with Make (O'Reilly, 1991).

Building Dynamic Link Libraries

Dynamic Link Library modules (DLLs) allow functions to be linked into an application at runtime as needed, rather than when the application is initially compiled and linked. McIDAS-X does not support dynamic link modules. Instead, it emulates dynamic linking at compile time by preprocessing the module to contain unique type-based names for the API functions and imbedded common blocks. The preprocessor program, convdlm (in convdlm.fp) automatically modifies the entry point names in a unique way to avoid duplication. This mechanism is normally used in McIDAS-X for the navigation and calibration subsystems. For this process to work,

Generating DLL subsystem functions

When adding a new dynamic link library to McIDAS-X, you must generate a new subsystem initialization function. For navigation, this function is named nvprep.for and for calibration it is named kbprep.for. This is most easily done using the nav_init script and cal_init scripts.

Generate new nvprep.for and kbprep.for functions so these functions can use the new navigation and calibration modules as well as the navigation and calibration in McIDAS-X. Note that ~mcidas/mcidasversion/src is the directory where the core McIDAS-X source can be found for the current version of McIDAS-X. For example, in version 2003, this file would be ~mcidas/mcidas2003/src.
To generate nvprep.for, run the command below at the Unix prompt in the directory containing your new navigation modules.
~mcidas/mcidasversion/src/nav_init ~mcidas/mcidasversion/src/nvx*.dlm -o nvprep.for
To generate kbprep.for, run the command below at the Unix prompt in the directory containing your new calibration modules.
~mcidas/mcidasversion/src/cal_init ~mcidas/mcidasversion/scr/kbx*.dlm kbx*.dlm -o kbprep.for
To allow applications to access your new navigation types, recompile nvprep.for and all applications that use navigation. For new calibration types, recompile kbprep.for and all applications that use calibration. For ADDE applications, the calibration is usually done on the server, requiring relinking of the ADDE servers.

Additional suggestions for writing DLL modules

Consider the guidelines below when writing a calibration or navigation module. Most restrictions are related to preprocessing the routine with convdlm.

Write the module in Fortran, since convdlm only runs against Fortran. Using a C module will require a manual modification of the entry point names.
Write the code in uppercase. When convdlm was written, all the modules were in uppercase. The only recognized comment line begins with a C.
Don't use the words SUBROUTINE, FUNCTION, or COMMON in comment lines or messages such as DDEST. Also, in these lines, don't enter the name of any subroutine, function, or common block in uppercase.
Don't use the Fortran ENTRY statement; convdlm doesn't recognize it or handle it correctly.
Don't embed a function call within another function call if both functions are in the module. convdlm can't handle the expansion and will print an error message and then exit. For example, if SUBROUTINE ASUB(K) and FUNCTION BFUNC(J) are both in the .DLM, the following is illegal:
CALL ASUB (BFUNC(10))
Don't allow routines that expect character variables to be passed in (KBXINI, KBXOPT, for example), to declare the variables as CHARACTER*(*). The length of the variable is not passed along. So, in KBXINI and KBXOPT, the lengths are known and are so declared as CHARACTER*4.
Don't output text with SDEST or Fortran WRITE, for example. This causes problems with ADDE servers that send data through standard output. You can embed DDEST calls for debugging, but they will only be output with non-ADDE commands.

To look at .f files, run the process convdlm manually, since these files are automatically deleted during compiling. When compiling .DLMs on Unix, convdlm reads the .DLM file and outputs three .f files: kbxtest.dlm becomes kbxtest1.f, kbxtest2.f, and kbxtest3.f. These files are compiled, so any compiler warnings and/or errors refer to these files, which have different line numbers for the statements than the .DLMs.

To run convdlm, use: convdlm filename
For example: convdlm kbxtext.dlm