This chapter provides the information you need to develop applications programs under McIDAS-X. You'll learn how to:
This chapter is organized into these sections:
In this section, you will learn how to establish a user account, which you and your system administrator will set up. You must have a user account to develop code in McIDAS-X. This user account is your development arena. From it, you can create and debug your own code and datasets without impacting other McIDAS-X users or developers.
Your user account will consist of these components:
Establishing a user account is a joint effort between you and your system administrator. The responsibilities of each are described below.
Your system administrator can create an individual Unix account for you, configuring the system to acknowledge you as a user and assigning basic privileges and directories.
In addition, the system administrator should install the McIDAS-X package on your workstation and place it in a separate account named mcidas . The mcidas account contains directories and files that you will use when developing code.
|
See Chapter 1 of the McIDAS User's Guide for instructions on installing the mcidas account. See Chapter 2 of that manual for additional information on setting up user accounts. |
Verify that the .profile (Korn shell) or .cshrc (C shell) file located in your user account's home directory contains the proper McIDAS-X- and vendor-specific directories. The presence and order of these directories in the environment variable PATH define the searching order when you run any command or script.
Insert these McIDAS-X-specific directories in your PATH in this order:
Also insert any required vendor-specific directories. Verify that the files and directories are placed in your PATH either by you, your system administrator, or the vendor. You can do this in your .profile file by appending your PATH environment variable. These directories contain the C compiler, the Fortran compiler, and other tools needed to develop your code.
|
See the section Preparing the mcidas Account in Chapter 1 of the McIDAS User's Guide for more information on modifying the PATH environment variable and a complete list of the required vendor-specific directories. |
When developing McIDAS-X code, you will use the following two types of directories:
The mcidas account directories are provided with the McIDAS-X software, but you must create your own user account directories. These directories are described below.
When the system administrator installs the McIDAS-X software in the mcidas user account, a series of predefined directories is automatically created. You don't need copies of these directories in your user account; however, knowing their contents can help you when developing code. They contain examples of source code and data files used with core applications.
The package directories contain the files for creating McIDAS-X. The names of the directories depend on the package name and version number. For example, the McIDAS-X version 200x package directories and their contents are shown in the table below.
|
Directory name |
Contents |
|---|---|
The installation directories contain the files that are automatically generated when McIDAS-X is installed. The table below lists the directories and their contents.
|
Directory |
Contents |
|---|---|
A user account directory is a directory that you create to hold your locally developed code. It can include your local library with its source code, applications with their source code, and data files.
The table below lists the suggested user account directories you should create before you begin writing any local code. The $HOME/mcidas, $HOME/mcidas/data, and $HOME/mcidas/help directories are created when mcidas is first started from the $HOME account.
|
Directory name |
Contents |
|---|---|
When you develop a new function for McIDAS-X, you must either add it to the McIDAS-X library or put it in a local library that you've created as part of your user account. The purpose of these libraries and some of the rules governing them are described below.
The McIDAS-X library, libmcidas.a , contains all the object code for the functions, subroutines, and Dynamic Link Modules that make up the McIDAS-X Application Program Interface (API). If you develop applications programs that link to libmcidas.a , be aware that the functions in this library are subject to change. SSEC reserves the right to modify or remove library functions.
You will receive a new library of functions and list of function changes with each McIDAS-X upgrade. The new library is in the file ~mcidas/lib/libmcidas.a .
When developing code, you will undoubtedly produce your own set of functions to support your applications, and need a local library to keep those functions with their applications' source code. Placing your functions in a local library allows you to isolate your local functions from the McIDAS-X core functions, making them less susceptible to naming collisions and eliminating the need to regenerate your functions after a McIDAS-X upgrade. A local library is also useful for referencing functions that SSEC has moved to the compatibility library.
Use the suggested conventions below when naming functions that you'll put in your local library. An example of creating and accessing a local library is provided in the next section, 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.
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 |
|---|---|
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 .
mccomp -c -I. -I/home/mcidas/inc program.pgm |
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 |
|---|---|
|
links the command with the a directory containing the libraries |
|
To link the object file program.o created in the previous example to create program.k , run the script below.
mccomp /home/mcidas/lib/main.o program.o -L/home/mcidas/lib -lmcidas -o program.k |
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 .
|
See the section Writing McIDAS-X applications in Chapter 2, Learning the Basics for more information about the MAIN program. |
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 .
mccomp -c -I. -I/home/mcidas/inc foo.f |
mcar libdev.a foo.o |
mccomp bar.o -L. -L/home/mcidas/lib -ldev -lmcidas -o bar.k |
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).
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,
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.
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 |
Consider the guidelines below when writing a calibration or navigation module. Most restrictions are related to preprocessing the routine with convdlm.
CALL ASUB (BFUNC(10)) |
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
The McIDAS-X command HELP allows users to quickly see the online structure of a command's argument list. When you write a McIDAS-X applications program, you should include a block of comments describing the functionality of the application, its positional parameters and keywords, and other notable remarks. This block of comments is called a program help or simply the help . These text comments, which reside in help files, form the input to the HELP command. The help files included in the McIDAS-X release are stored in ~mcidas/help .
Use the utility mcmkhelp to produce a help file from source code. This script reads a source file from standard input and writes a help template to standard output. For example, the script below creates a help file from the source file bar.pgm then stores the resulting help template in your own mcidas help directory.
mcmkhelp < bar.pgm > $HOME/mcidas/help/bar.hlp |
|
For more information about the HELP command, see the McIDAS User's Guide. For more information about the HELP command format, see Chapter 2 in this manual. |
